-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathsearchbnf.conf.spec
210 lines (198 loc) · 8.33 KB
/
searchbnf.conf.spec
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
# Version 9.4.0
#
#
#########################################################################
# OVERVIEW
#########################################################################
# This file contains descriptions of the settings that you can use to
# configure the search assistant to display information in the
# UI about custom search commands.
#
# Each stanza in your local searchbnf.conf file controls a separate
# custom search command or an option to a command.
#
# There is a searchbnf.conf file in the $SPLUNK_HOME/etc/system/default/ directory.
# which is used to display information about the built-in search commands
# in the UI through the search assistant.
# Never change or copy the configuration files in the default directory.
# The files in the default directory must remain intact and in their
# original location.
#
# To set custom configurations, create a new file with the name
# "searchbnf.conf" in the
# $SPLUNK_HOME/etc/apps/<appname>/default/ directory.
# Then add the custom commands to the custom configuration file.
# For examples, see the "searchbnf.conf.example" file.
#
# You must restart the Splunk instance to enable configuration changes.
#
# To learn more about configuration files, including precedence, see the
# documentation located at
# http://docs.splunk.com/Documentation/Splunk/latest/Admin/Aboutconfigurationfiles
#
#########################################################################
# GENERAL FORMATTING
#########################################################################
# * Adjacent tokens implicitly allow no whitespace.
# * All literals are case-insensitive.
# * Whitespace (including newlines) match \s+
#
#########################################################################
# DESCRIPTION FORMATTING
#########################################################################
# * For the command description, when automatically converted to html
# multiple whitespaces are removed.
# * For descriptions that extend to multiple lines end each line with
# a backslash "\", except the last line.
# * To create a multi-paragraph description, use \p\ to cause a paragraph
# break.
# * To force a new line and indent, use \i\ to cause a newline and
# indent 4 spaces (<br> )
# * <terms> are italicized.
# * UPPERCASETERMS and quoted terms are put into <code/> and render in
# green text, in a slightly smaller font.
#
#########################################################################
# SYNTAX FORMATTING
#########################################################################
# * Reserved characters are ("<>()|?*+") and <tokens>, everything else
# is taken literally. Those characters need to be quoted.
# Use \" to represent a quote.
# * This file uses regex-like grouping and nomenclature for the syntax:
# (): grouping
# <term> : <term> is required
# (<term>)? : <term> is optional
# (<term>)* : <term> is optional and repeated 0 or more times
# (<term>)+ : <term> is required and repeated 1 or more times
#
# * <terms> can be named for readability with a colon and a default value
# For example, if you have a term called "field", instead of the
# syntax "...<field> AS <field>" you can add a qualifer to the term
# name, such as "<field:fromfield> AS <field:tofield>" and then define
# "field" as a <string>.
#########################################################################
# STANZAS
#########################################################################
# There are two types of stanzas, search command stanzas and options stanzas.
#
#[<command-name>-command]
# * The command stanza contains the name of the custom search command
# and "-command" enclosed in square brackets.
# For example, "geocode-command”.
# * A searchbnf.conf file can contain multiple command stanzas,
# one command stanza for each command.
# * Follow the command stanza with attribute/value pairs that define
# the properties for the custom search command.
# Some attributes are required. See ATTRIBUTES.
# * If you do not set an attribute for a given <spec>, the default
# is used. The default values are empty.
# * Search command syntax can refer to command options. These options
# must be defined below the command stanza in separate options stanzas.
# It is possible to use nested options stanzas.
# For example:
#
# [geocode-command]
# syntax = geocode (geocode-options)*
# ...
# [geocode-options]
# syntax = (maxcount=<int>) | (maxhops=<int>) | (coordinate-options)+
# ...
# [coordinate-options]
# syntax = (latitude-field=<string>) | (longitude-field=<string>)
# ...
#
#########################################################################
# COMMAND STANZA STRUCTURE
#########################################################################
#
# [<command-name>-command]
# syntax (Required)
# simplesyntax (Optional)
# alias (Optional)
# description (Required)
# shortdesc (Optional)
# example<number> (Optional)
# comment<number> (Optional)
# usage (Required)
# tags (Optional)
# maintainer (Deprecated)
# appears-in (Deprecated)
# related (Optional)
#########################################################################
# ATTRIBUTES
#########################################################################
# The attribute/value pair descriptions for custom search commands.
syntax = <string>
* The syntax of the custom search command. The format is:
syntax=<command-name> (attribute-name=<datatype>) (attribute-name=<datatype>)
* See SYNTAX FORMATTING.
* Required
simplesyntax = <string>
* Simpler version of the syntax to make it easier to understand,
at the expense of completeness. Use only if the syntax is complex.
* Typically the simplesyntax removes rarely used options or alternate
ways of saying the same thing.
* For example, a search command might accept values such as
"m|min|mins|minute|minutes", but that would unnecessarily clutter
the syntax description for the user. For the simplesyntax you can
use one value such as "minute".
* Optional
alias = <alias list>
* Alternative names for the search command.
Specifying an alias is discouraged.
Users might get confused when more than one name is used for the
same command.
* Optional
description = <string>
* A detailed description of the search command.
See DESCRIPTION FORMATTING.
* If a shortdesc is specified, the description appears only in the
search assistant "Full" mode. Displays under the heading "Details"
when users click "More".
* See the "searchbnf.conf.example" file for an example.
* Required
shortdesc = <string>
* A one sentence description of the search command. If specified,
appears in both the "Full" and "Compact" search assistant modes.
* Specify a shortdesc when the description is multiple sentences long.
* Optional
example<number> = <string>
comment<number> = <string>
* The "example" should show a common example of using the search command,
with 1 or more attributes.
* The "comment" should explain what the command is doing in the example.
* You can specify multiple examples by appending a matching number to
the example and corresponding comment.
* For example:
example1 = geocode maxcount=4
comment1 = run geocode on up to four values
example2 = geocode maxcount=-1
comment2 = run geocode on all values
* In Compact mode, only the first example displays in the search assistant.
* In Full mode, the top three examples display in the search assistant.
* Optional, but recommended
usage = public | private | deprecated
* Specifies if a command is public, private, or deprecated.
* The search assistant only operates on public commands.
* Required
tags = <tag list>
* One or more words that users might type into the search bar which are
similar to the command name. The UI displays the command names
associated with the tags.
* For example, when a user types "graph" or “report” for the "chart"
command.
* Optional
maintainer = <name>
* The name of person who originally worked on the command or who is
responsible for the command now.
* Does not appear in the search assistant.
* Deprecated
appears-in = <version>
* The version that the custom command first appeared in.
* Does not appear in the search assistant.
* Deprecated
related = <command list>
* List of SPL commands related to this command.
* Might help users learn about other, related commands.
* Displays in the search assistant Full mode when users click “More”.
* Optional