When to escape characters
When using SPL2, use the backslash character ( \ ) to ignore characters that have special meaning in a search, such as quotation marks, pipes, and the backslash character itself.
Alternatives to using escape characters
In some situations, you can avoid using escape characters by using a search literal or raw string literal instead.
Search literals
A search literal is a way to search for one or more terms that appear in your data.
For example, suppose you have a series of logon events that include failed passwords events such as this:
Failed password for user "ladron" from 192.0.2.0/24 port 1047 ssh2
You want to search for the terms user "ladron" from 192.0.2.0/24
in these events. To search for these terms you can use a search literal. With a search literal, an AND condition is implied between each of the terms.
Internally the search becomes user AND "ladron" AND from AND 192.0.2.0/24
You must enclose the terms in backtick characters ( ` ). The quoted string inside the set of terms doesn't need to be escaped.
You specify the search literal in the WHERE clause of the from
command:
... WHERE `user "ladron" from 192.0.2.0/24`
For more information, see Search literals in expressions.
Raw string literals
A raw string literal is an expression in which the backspace character ( \ ) is not processed.
Raw string literals must be preceded by the at symbol ( @ ) and enclosed in double quotation marks. If a double quotation occurs in the string, it must be escaped using another double quotation.
For example, you want to specify the path C:\windows
in your search. This path is a string value and normally you need to escape the backslash character ( \ ) to have the search ignore the backslash in the string. As with all strings, it must be enclosed in double quotation marks.
To use the escaping nomenclature for this string, you specify "C:\\windows"
.
However, instead of escaping the backslash character, you can designate the path C:\windows
as a raw string and precede the string with the at symbol ( @ ). For example: @"C:\windows"
.
For more information about raw string literals, see Types of expressions
Escape sequences
An escape sequence is a set of characters used in string literals that have a special meaning, such as a new line, a new page, or a tab. For example, the escape sequence \n
represents a new line character.
To ignore an escape sequence in your search, prepend a backslash character to the escape sequence. For example, specify \\n
to ignore the new line escape sequence.
When you apply a backslash to an escape sequence that is inside quotation marks, the escape sequence is expanded inside the quotation marks.
Characters and escape sequences that must be escaped
The following table shows the characters and escape sequences that must be escaped in your searches:
Character or escape sequence | Description |
---|---|
" | Quotation marks. |
\ | Backslash character. |
\b | Backspace escape sequence. |
\f | Page Break escape sequence. Also referred to as the Formfeed Page Break escape sequence. |
\n | New Line escape sequence |
\r | Return escape sequence. Also referred to as the Carriage Return escape sequence. |
\t | Tab escape sequence. Also referred to as the Horizontal Tab escape sequence. |
To escape a double quotation mark ( " ), use the sequence \"
to search for a literal double quotation mark. To escape a backslash character ( \ ), use the sequence \\
to search for a backslash.
When an escape sequence is sent to a SPL2 command that the command doesn't recognize, an error is returned. For example, the new line \n
in a search string is not a known escape sequence. So when \n
is sent to a command, an error is returned. However, \\n
is a known escape sequence. The escape sequence \\n
is interpreted and sent to the command as \n
.
Rules for when to use escape characters
The following table explains the circumstances in which you need to use escape characters:
Data type | Rules |
---|---|
String values | String values must be enclosed in double quotation marks ( " ).
If a string value contains a double quotation mark ( " ), that double quotation mark must be escaped. Otherwise, the search will misinterpret where the string value ends.
If you don't escape the quotation marks around the username |
Field names | Field names that contain anything other than letters, numbers, or the underscore ( _ ) character must be enclosed in single quotation marks ( ' ).
|
Search literals | Search literals must be enclosed in backtick characters ( ` ).
|
Examples
In addition to the previous examples, the following sections show more examples.
Escaping quotation marks
When you want to search for values that contain quotation marks, using the rules in the preceding section, you must escape the quotation marks.
Consider the following events:
_raw |
---|
The user "vpatel" isn't authenticated. |
The user "amartin" is not found. |
Anytime you search for string values, you must enclose the values in double quotation marks ( " ).
To search string values that contain double quotation marks, such as "amartin"
, you need to escape the double quotation marks that surround the name. Your search must look like this:
... WHERE name="\"amartin\""...
Here's another example.
Consider the following JSON. The text
values contain quotation marks, which are escaped using the backslash character ( \ ):
{ quote: { name:"Hamlet", text:"\"To be, or not to be, that is the question:\"" }, quote: { name:"Maya Angelou", text:"\"You may not control all the events that happen to you, but you can decide not to be reduced by them.\"" }, quote: { name:"Ralph Waldo Emerson", text:"\"To be yourself in a world that is constantly trying to make you something else is the greatest accomplishment.\"" } }
To search for all text
objects that contain values that start with "To be
, you need to use a wildcard. The WHERE clause does not support the asterisk character ( * ) wildcard. Instead, you must use the like
function in the WHERE clause to search using a wildcard. The like
function uses the percent sign ( % ) as a wildcard character.
The search looks like this:
| FROM
[{
quote:{name:"Hamlet", text:"\"To be or not to be that is the question:\""},
quote:{name:"Maya Angelou", text:"\"You may not control all the events that happen to you, but you can decide not to be reduced by them.\""},
quote:{name:"Ralph Waldo Emerson", text:"\"To be yourself in a world that is constantly trying to make you something else is the greatest accomplishment.\""}
}]
WHERE 'quote' LIKE "%\"To be%"
This search returns the quotes from Hamlet and Ralph Waldo Emerson.
The like
function supports several syntaxes, see Comparison and Conditional functions.
This example uses a dataset literal so that you can see what is being searched for. See Dataset literals.
Escaping backslashes
The most common example of escaping backslashes is with Windows file paths. Suppose you want to search for the path C:\windows\temp
in your events. You must escape the backslashes ( \ ):
...WHERE path="C:\\windows\\temp"
See also
- Related information
- SPL2 and regular expressions
Quotation marks | Event segmentation and searching |
This documentation applies to the following versions of Splunk® Cloud Services: current
Feedback submitted, thanks!