Documentation: 3.2.3
|  Print Version Contents
This page last updated: 08/05/08 11:08am

Search in the CLI

Run searches in the CLI using the CLI search command. Searches in the CLI work the same way as searches in Splunk Web except there is no timeline rendered with the search results, and a time range isn't specified by default.

Access these CLI help pages from the command line for help with CLI searches:

For a complete list of search commands available in the CLI type:

./splunk help search-commands

For a quick reference on CLI search command syntax type: 

./splunk help commands

CLI Search syntax

In general, the syntax you use for search commands and arguments in the CLI is the same as you use in Splunk Web. In Splunk Web the search command is automatically prepended to a search when you use the search bar. You can search for anything you would normally search for in the CLI by using the CLI search command.

When you search using the CLI search command, quote the search string (argument of the search command) with single-quotes. You can use double-quotes, but this can cause parsing errors when you use double-quotes to express field arguments.

General form of a CLI search command string:

./splunk search 'search string' [-parameter]

Example:
This search selects events whose _raw field contains ip addresses in the non-routable class A (10.0.0.0/8).

./splunk search '* | regex _raw="(?<!\d)10.\d{1,3}\.\d{1,3}\.\d{1,3}(?!\d)" '

Differences between CLI and Splunk Web searches

  • Remember to quote search strings using single quotes to avoid any parsing errors.
  • You can't use search commands that produce charts or graphs in the CLI.
  • Use * to search for all events in a CLI search (example: ./splunk search '* | top' - returns top 10 events from all your data).
  • Use time-based search modifiers to specify time ranges for your CLI searches.

Examples

These examples illustrate the difference between searches in Splunk Web and searches in the CLI.

This example selects events whose _raw field contains IP addresses in the non-routable class A (10.0.0.0/8).

Splunk Web:

| regex _raw=(?<!\d)10.\d{1,3}\.\d{1,3}\.\d{1,3}(?!\d)Search

CLI:

./splunk search '* | regex _raw="(?<!\d)10.\d{1,3}\.\d{1,3}\.\d{1,3}(?!\d)" '

This example returns all URLs that have 404 errors but not 303 errors.

Splunk Web:

index=sampledata | set diff [search 404 | select url] [search 303 | fields url]Search

CLI:
./splunk search ' index="sampledata" | set intersect [search "404 | select url"] [search "303 | fields url"] '

This example extracts the COMMAND field only when it occurs in rows that contain "splunkd".

Splunk Web:

| multikv fields COMMAND filter splunkdSearch

CLI:
./splunk search ' * | multikv fields COMMAND filter splunkd '

Asynchronous searches (dispatch CLI command)

The Splunk CLI allows you to run multiple searches asynchronously using the dispatch CLI command. Use dispatch to report on a large amount of data where the search could take days and you still want to be able to run other searches with Splunk. dispatch works the same way as search except you are not limited to running a single search. Set when to end a dispatch search by setting a maximum time (-maxtime) or a maximum number of results to output (-maxout).

To run more than one dispatch (search):
1. Execute a dispatch command in your current shell window.
2. (Leave your current window open.) Open a new shell window.
3. Execute another dispatch command.
Repeat!

Access the dispatch CLI help page at the command line for full detail of its syntax:

./splunk help dispatch

Note: Use dispatch to search without a maximum result limit.

Syntax

dispatch uses the same syntax as the CLI search command.

./splunk dispatch 'search string' [-parameter]

Optional parameters

-maxout Set the maximum number of results to return from the search string (default=100).
-maxtime Set the maximum number of seconds to run the search (default=0 or no limit).

Caution: Do not set the optional parameter -maxout to a large value near the max value. Setting a large value causes Splunk to hang indefinitely in some cases.

Examples

This example starts a search for events on all sources that contain "hot" and returns the count of events. The maxtime parameter sets the search to only run for 3 seconds.

./splunk dispatch "source=*hot* | stats count" -maxtime 3

This example searches for events from the access source types with byte counts greater than 1000. The maxout parameter sets the search to run until its returned 200 search results.

./splunk dispatch "sourcetype=access* bytes>1000" -maxout 200

CLI search parameters

maxresults

By default, Splunk returns 100 search results when you search in the CLI. Splunk also passes only 100 search results as arguments to search commands in your search pipeline. Change the maximum number of results passed to search commands by using the -maxresults parameter of the CLI search command.

Set a new value for maxresults (0-50000) by adding the maxresults parameter after your search string.

Caution: Setting -maxresults to a high value causes searches to run very slow. Splunk recommends that you search in Splunk Web if you want your search to return a higher number of results.

Syntax:

./splunk search 'search string' -maxresults <value>

Example:

This example searches for 404's from web server events and returns only 5000 events (by setting -maxresults 5000).

./splunk search '404 host=webserver bigcompany.com | top source'  -maxresults 5000

Previous: The Splunk CLI    |    Next: Form search

Comments

  1. The "remote * [search ..." search is still in the product, but it is deprecated and should be replaced with dispatch. It's also effectively broken, at least in the format that people would expect. You can still get it to work, but it requires some trickery to convince the cli parser to actually let the search go through.

    For example, I used to test distributed with the following search:
    splunk/bin/splunk search "remote * [search ishmael] | outputcsv"

    That no longer works. To get that to work I had to do:
    splunk/bin/splunk search "|page 0-10 100 [remote * [search ishmael]] | outputcsv"

    Note the leading | and the extra ].

    As opposed to:
    splunk/bin/splunk dispatch "ishmael" -format csv
    Posted by joecarpenter on Mar 28 2008, 11:43am

  2. The -maxout parameter allows you to stop the dispatch search at a maximum result limit that you specify. It has a default, but you can set it to any number you want theoretically.
    Posted by jrosensteel on Mar 19 2008, 5:14pm

  3. "Note: You can use the dispatch CLI command to search without a maximum result limitation."

    This does not appear to be true.

    The splunk cli documentation conflicts:

    splunk help dispatch
    .
    .
    maxout Set the maximum number of results to return from the search string (default=100)

    # splunk dispatch "source::/var/log/messages" -auth admin:changeme|wc -l
    100
    Posted by dmourati on Mar 19 2008, 5:02pm

  4. What happened to remote searches like this:

    /opt/splunk/bin/splunk search "remote * [search source::/var/log/tomcat55/catalina.out minutesago::5]" -auth admin:changeme

    I couldn't find anything in the documentation.

    Thanks.
    Posted by dmourati on Mar 19 2008, 10:00am

Log in to comment.