Downloads |
Table Of Contents
CLI String Search
Feature Summary
The Command Line Interface (CLI) String Search feature allows you to search or filter any show or more command output. This is useful when you need to sort though large amounts of output, or if you want to exclude output that you do not need to see.
CLI String Search also allows for searching and filtering at --More-- prompts. This new capability is introduced in Cisco IOS Release 12.0 T.
With the search function, you can begin unfiltered output at the first line that contains a regular expression you specify. You can then specify a maximum of one filter per command or start a new search from the --More-- prompt.
A regular expression is a pattern (a phrase, number, or more complex pattern) the CLI String Search feature matches against show or more command output. Regular expressions are case sensitive and allow for complex matching requirements.
You can perform two types of filtering:
•
Include output lines that contain a specified regular expression.
•
You can then search this filtered output at the --More-- prompts.
Benefits
The CLI String Search feature offers the following benefits:
•
•
List of Terms
The following terms pertain to the CLI String Search feature:
Command Line Interface (CLI)—An interface that allows the user to interact with the operating system by entering commands and optional arguments. The UNIX operating system, DOS, and Cisco IOS software provide CLIs.
--More-- prompt—A Cisco IOS prompt that appears when output continues beyond what is displayed on your screen. Pressing Return displays the next line; pressing the Spacebar displays the next screen of output. The CLI String Search feature allows you to search or filter output from --More-- prompts.
regular expression—A pattern (a phrase, number, or more complex pattern) the CLI String Search feature matches against show or more command output. Regular expressions are case sensitive and allow for complex matching requirements. Examples of simple regular expressions are Serial, misses, 138. Examples of complex regular expressions are 00210..., ( is ), [Oo]utput.
Restrictions
The following restrictions apply to the CLI String Search feature:
•
•
Platforms
This feature is supported on all Cisco IOS Release 12.0 T platforms currently using show commands, more commands, or --More-- prompts.
Prerequisites
Cisco devices need Cisco IOS Release 12.0 T software or later releases of Cisco IOS 12.0 T to use the CLI Search String feature.
Functional Description
This section describes regular expressions. They are patterns that the CLI String Search feature matches against show or more command output. Matching a string to the specified pattern (the regular expression) is called "pattern matching." Pattern matching either succeeds or fails.
Regular Expressions
A regular expression can be a single-character pattern or a multiple-character pattern. That is, a regular expression can be a single character that matches the same single character in the command output or multiple characters that match the same multiple characters in the command output. The pattern in the command output is referred to as a string. This section describes creating both single-character patterns and multiple-character patterns. It also discusses creating more complex regular expressions using multipliers, alternation, anchoring, and parentheses.
Single-Character Patterns
The simplest regular expression is a single character that matches the same single character in the command output. You can use any letter (A-Z, a-z) or digit (0-9) as a single-character pattern. You can also use other keyboard characters (such as ! or ~) as single-character patterns, but certain keyboard characters have special meaning when used in regular expressions. lists the keyboard characters with special meaning.
To use these special characters as single-character patterns, remove the special meaning by preceding each character with a backslash (\). The following examples are single-character patterns matching a dollar sign, an underscore, and a plus sign, respectively.
\$ \_ \+
You can specify a range of single-character patterns to match against command output. For example, you can create a regular expression that matches a string containing one of the following letters: a, e, i, o, and u. One and only one of these characters must exist in the string for pattern matching to succeed. To specify a range of single-character patterns, enclose the single-character patterns in square brackets ([ ]). For example,
[aeiou]
matches any one of the five vowels of the lowercase alphabet, while
[abcdABCD]
matches any one of the first four letters of the lower- or uppercase alphabet.
You can simplify ranges by entering only the end points of the range separated by a dash (-). Simplify the previous range as follows:
[a-dA-D]
To add a dash as a single-character pattern in your range, include another dash and precede it with a backslash:
[a-dA-D\-]
You can also include a right square bracket (]) as a single-character pattern in your range. To do so, enter the following:
[a-dA-D\-\]]
The previous example matches any one of the first four letters of the lower- or uppercase alphabet, a dash, or a right square bracket.
You can reverse the matching of the range by including a caret (^) at the start of the range. The following example matches any letter except the ones listed.
[^a-dqsv]
The following example matches anything except a right square bracket (]) or the letter d:
[^\]d]
Multiple-Character Patterns
When creating regular expressions, you can also specify a pattern containing multiple characters. You create multiple-character regular expressions by joining letters, digits, or keyboard characters that do not have special meaning. For example, a4% is a multiple-character regular expression. Put a backslash in front of the keyboard characters that have special meaning when you want to remove their special meaning.
With multiple-character patterns, order is important. The regular expression a4% matches the character a followed by a 4 followed by a % sign. If the string does not have a4%, in that order, pattern matching fails. The following multiple-character regular expression
a.
uses the special meaning of the period character to match the letter a followed by any single character. With this example, the strings ab, a!, or a2 are all valid matches for the regular expression.
You can remove the special meaning of the period character by putting a backslash in front of it. In the following expression
a\.
only the string a. matches this regular expression.
You can create a multiple-character regular expression containing all letters, all digits, all keyboard characters, or a combination of letters, digits, and other keyboard characters. The following examples are all valid regular expressions:
telebit 3107 v32bis
Multipliers
You can create more complex regular expressions that instruct Cisco IOS software to match multiple occurrences of a specified regular expression. To do so, you use some special characters with your single- and multiple-character patterns. lists the special characters that specify "multiples" of a regular expression.
The following example matches any number of occurrences of the letter a, including none:
a*
The following pattern requires there to be at least one letter a in the string to be matched:
a+
The following pattern matches the string bb or bab:
ba?b
The following string matches any number of asterisks (*):
\**
To use multipliers with multiple-character patterns, you enclose the pattern in parentheses. In the following example, the pattern matches any number of the multiple-character string ab:
(ab)*
As a more complex example, the following pattern matches one or more instances of alphanumeric pairs (but not none; that is, an empty string is not a match):
([A-Za-z][0-9])+
The order for matches using multipliers (*, +, or ?) is to put the longest construct first. Nested constructs are matched from outside to inside. Concatenated constructs are matched beginning at the left side of the construct. Thus, the regular expression matches A9b3, but not 9Ab3 because the letters are specified before the numbers.
Alternation
Alternation allows you to specify alternative patterns to match against a string. You separate the alternative patterns with a vertical bar (|). Exactly one of the alternatives can match the string. For example, the regular expression
codex|telebit
matches the string codex or the string telebit, but not both codex and telebit.
Anchoring
You can instruct Cisco IOS software to match a regular expression pattern against the beginning or the end of the string. That is, you can specify that the beginning or end of a string contain a specific pattern. You "anchor" these regular expressions to a portion of the string using the special characters shown in .
Table 3 Special Characters Used for Anchoring
^
Matches the beginning of the string.
$
Matches the end of the string.
There is another use for the ^ symbol. For example, the following regular expression matches an string only if the string starts with abcd:
^abcd
Whereas the following expression is in a range that matches any single letter, as long as it is not the letters a, b, c, or d:
[^abcd]
With the following example, the regular expression matches a string that ends with .12:
$\.12
Contrast these anchoring characters with the special character underscore (_). Underscore matches the beginning of a string (^), the end of a string ($), parentheses ( ) , space ( ), braces { }, comma (,), or underscore (_). With the underscore character, you can specify that a pattern exist anywhere in the string. For example,
_1300_
matches any string that has 1300 somewhere in the string. The string's 1300 can be preceded by or end with a space, brace, comma, or underscore. So, while
{1300_
matches the regular expression, 21300 and 13000 do not.
Using the underscore character, you can replace long regular expression lists, such as the following:
^1300$ ^1300(space) (space)1300 {1300, ,1300, {1300} ,1300, (1300
with simply _1300_.
Parentheses for Recall
As shown in the "Multipliers" section, you use parentheses with multiple-character regular expressions to multiply the occurrence of a pattern. You can also use parentheses around a single- or multiple-character pattern to instruct the Cisco IOS software to remember a pattern for use elsewhere in the regular expression.
To create a regular expression that recalls a previous pattern, you use parentheses to indicate memory of a specific pattern and a backslash (\) followed by an integer to re-use the remembered pattern. The integer specifies the occurrence of a parentheses in the regular expression pattern. If you have more than one remembered pattern in your regular expression, then \1 indicates the first remembered pattern, and \2 indicates the second remembered pattern, and so on.
The following regular expression uses parentheses for recall:
a(.)bc(.)\1\2
This regular expression matches an a followed by any character (call it character #1), followed by bc followed by any character (character #2), followed by character #1 again, followed by character #2 again. So, the regular expression can match aZbcTZT. The software remembers that character #1 is Z and character #2 is T and then uses Z and T again later in the regular expression.
Configuration Tasks
The CLI search string provides the following new options for existing show and more commands, and the --More-- prompt:
Search show Command Output
To search show command output, use the following command in EXEC mode:
show any-command | begin regular-expression
Begin unfiltered output of the show any-command with the first line that contains the regular expression.
Ctrl-^
Interrupt output.
Filter show Command Output
To filter show command output, use one of the following commands in EXEC mode:
Note
Search more Command Output
You can search more commands the same way you search show commands. To search more command output, use the following command in EXEC mode:
more any-command | begin regular-expression
Begin unfiltered output of the more any-command with the first line that contains the regular expression.
Ctrl-^
Interrupt output.
Filter more Command Output
You can filter more commands the same way you filter show commands. To filter more command output, use one of the following commands in EXEC mode:
Search from --More-- Prompt
You can search output from --More-- prompts. To search show or more command output from a --More-- prompt, use the following command in EXEC mode:
/regular-expression
Begin unfiltered output with the first line that contains the regular expression.
Ctrl-^
Interrupt output.
Filter from --More-- Prompt
You can filter output from --More-- prompts. However, you can only specify one filter for each command's output. The filter remains until the show or more command output finishes or until you interrupt the output (using Ctrl-^).Therefore, you cannot add a second filter at a --More-- prompt if you already specified a filter at the original command or at a previous --More--prompt.
To filter show or more command output at a --More-- prompt, use one of the following commands in EXEC mode:
Configuration Examples
The following is partial sample output of the more nvram:startup-config | begin command that begins unfiltered output with the first line that contain the regular expression "ip." At the --More-- prompt, the user specifies a filter to exclude output lines that contain the regular expression "ip."
router# more nvram:startup-config | begin ipip subnet-zeroip domain-name cisco.comip name-server 198.92.30.32ip name-server 171.69.2.132!isdn switch-type primary-5ess...interface Ethernet1ip address 5.5.5.99 255.255.255.0--More---ipfiltering...media-type 10BaseT!interface Serial0:23encapsulation frame-relayno keepalivedialer string 4001dialer-group 1isdn switch-type primary-5essno fair-queueThe following is partial sample output of the more nvram:startup-config | include command. It only displays lines that contain the regular expression "ip."
router# more nvram:startup-config | include ipip subnet-zeroip domain-name cisco.comip name-server 198.92.30.32ip name-server 171.69.2.132The following is partial sample output of the more nvram:startup-config | exclude command. It excludes lines that contain the regular expression "service." At the --More-- prompt, the user searches for the regular expression "Dialer1." This continues filtered output with the first line that contains "Dialer1."
router# more nvram:startup-config | exclude service!version 12.0!hostname router!boot system flashno logging buffered!ip subnet-zeroip domain-name cisco.com...--More--/Dialer1filtering...interface Dialer1no ip addressno ip directed-broadcastdialer in-bandno cdp enableThe following is partial sample output of the show interface | begin command that begins unfiltered output with the first line that contains the regular expression "Ethernet." At the --More-- prompt, the user specifies a filter to include only the lines that contain the regular expression "Serial."
router# show interface | begin EthernetEthernet0 is up, line protocol is upHardware is Lance, address is 0060.837c.6399 (bia 0060.837c.6399)Description: ip address is 172.1.2.14 255.255.255.0Internet address is 172.1.2.14/24...0 lost carrier, 0 no carrier0 output buffer failures, 0 output buffers swapped out--More--+Serialfiltering...Serial1 is up, line protocol is upSerial2 is up, line protocol is upSerial3 is up, line protocol is downSerial4 is down, line protocol is downSerial5 is up, line protocol is upSerial6 is up, line protocol is upSerial7 is up, line protocol is upThe following is partial sample output of the show buffers | exclude command. It excludes lines that contain the regular expression "0 misses." At the --More-- prompt, the user searches for the regular expression "Serial0." This continues the filtered output with the first line that contains "Serial0."
router# show buffers | exclude 0 missesBuffer elements:398 in free list (500 max allowed)Public buffer pools:Small buffers, 104 bytes (total 50, permanent 50):50 in free list (20 min, 150 max allowed)551 hits, 3 misses, 0 trims, 0 createdBig buffers, 1524 bytes (total 50, permanent 50):49 in free list (5 min, 150 max allowed)Very Big buffers, 4520 bytes (total 10, permanent 10):...Huge buffers, 18024 bytes (total 0 permanent 0):0 in free list (0 min, 4 max allowed)--More--/Serial0filtering...Serial0 buffers, 1543 bytes (total 64, permanent 64):16 in free list (0 min, 64 max allowed)48 hits, 0 fallbacksThe following is partial sample output of the show interface | include command. It only displays lines that contain the regular expression "( is )." The parenthesis force the inclusion of the spaces before and after "is." This ensures that only lines containing "is" with a space both before and after it will be included in the output. This excludes lines with words like "disconnect."
router# show interface | include ( is )ATM0 is administratively down, line protocol is downHardware is ATMizer BX-50Dialer1 is up (spoofing), line protocol is up (spoofing)Hardware is UnknownDTR is pulsed for 1 seconds on resetEthernet0 is up, line protocol is upHardware is Lance, address is 0060.837c.6399 (bia 0060.837c.6399)Internet address is 172.21.53.199/24Ethernet1 is up, line protocol is upHardware is Lance, address is 0060.837c.639c (bia 0060.837c.639c)Internet address is 5.5.5.99/24Serial0:0 is down, line protocol is downHardware is DSX1...--More--At the --More-- prompt, the user searches for the regular expression "Serial0:13." This continues filtered output with the first line that contains "Serial0:13."
/Serial0:13filtering...Serial0:13 is down, line protocol is downHardware is DSX1Internet address is 11.0.0.2/80 output errors, 0 collisions, 2 interface resetsTimeslot(s) Used:14, Transmitter delay is 0 flagCommand Reference
This section documents new or modified commands. All other commands used with this feature are documented in the Cisco IOS Release 12.0 command references.
All more and show commands have been modified to include the CLI string search options. This section describes these modifications.
more begin
To search the output of any more command, use the more begin command in EXEC mode. This command begins unfiltered output of the more command with the first line that contains the regular expression you specify.
more any-command | begin regular-expression
To search the remaining output of the more command, use the following command at the --More-- prompt:
/regular-expression
To filter the remaining output of the more command, use one of the following commands at the --More-- prompt:
-regular-expression
+regular-expressionSyntax Description
Command Mode
EXEC
Usage Guidelines
This modification to more commands first appeared in Cisco IOS Release 12.0(1)T.
The regular-expression argument is case sensitive and allows for complex matching requirements.
You can specify a new search at every --More-- prompt.
Note
Because prior output is not saved, you cannot search or filter backward through prior output.
When output volume is large, the search can produce long lists of output. To interrupt this output, press Ctrl-^.
Sample Display
The following is partial sample output of the more nvram:startup-config | begin command that begins unfiltered output with the first line that contain the regular expression "ip." At the --More-- prompt, the user specifies a filter to exclude output lines that contain the regular expression "ip."
router# more nvram:startup-config | begin ipip subnet-zeroip domain-name cisco.comip name-server 198.92.30.32ip name-server 171.69.2.132!isdn switch-type primary-5ess...interface Ethernet1ip address 5.5.5.99 255.255.255.0--More---ipfiltering...media-type 10BaseT!interface Serial0:23encapsulation frame-relayno keepalivedialer string 4001dialer-group 1isdn switch-type primary-5essno fair-queueRelated Commands
more exclude
more include
show begin
show exclude
show includemore exclude
To filter more command output so that it excludes lines that contain a particular regular expression, use the more exclude command in EXEC mode.
more any-command | exclude regular-expression
To search the remaining output of the more command, use the following command at the --More-- prompt:
/regular-expression
Syntax Description
Command Mode
EXEC
Usage Guidelines
This modification to more commands first appeared in Cisco IOS Release 12.0(1)T.
The regular-expression argument is case sensitive and allows for complex matching requirements.
You can specify a new search at every --More-- prompt.
Note
Because prior output is not saved, you cannot search or filter backward through prior output.
When output volume is large, the search can produce long lists of output. To interrupt this output, press Ctrl-^.
Sample Display
The following is partial sample output of the more nvram:startup-config | exclude command. It excludes lines that contain the regular expression "service." At the --More-- prompt, the user searches for the regular expression "Dialer1." This continues filtered output with the first line that contains "Dialer1."
router# more nvram:startup-config | exclude service!version 12.0!hostname router!boot system flashno logging buffered!ip subnet-zeroip domain-name cisco.com...--More--/Dialer1filtering...interface Dialer1no ip addressno ip directed-broadcastdialer in-bandno cdp enableRelated Commands
more begin
more include
show begin
show exclude
show includemore include
To filter more command output so that it only displays lines that contain a particular regular expression, use the more include command in EXEC mode.
more any-command | include regular-expression
To search the remaining output of the more command, use the following command at the --More-- prompt:
/regular-expression
Syntax Description
Command Mode
EXEC
Usage Guidelines
This modification to more commands first appeared in Cisco IOS Release 12.0(1)T.
The regular-expression argument is case sensitive and allows for complex matching requirements.
You can specify a new search at every --More-- prompt.
Note
Because prior output is not saved, you cannot search or filter backward through prior output.
When output volume is large, the search can produce long lists of output. To interrupt this output, press Ctrl-^.
Sample Display
The following is partial sample output of the more nvram:startup-config | include command. It only displays lines that contain the regular expression "ip."
router# more nvram:startup-config | include ipip subnet-zeroip domain-name cisco.comip name-server 198.92.30.32ip name-server 171.69.2.132description ip address 172.21.53.199 255.255.255.0ip address 172.21.53.199 255.255.255.0Related Commands
more begin
more exclude
show begin
show exclude
show includeshow begin
To search the output of any show command, use the show begin command in EXEC mode.
show any-command | begin regular-expression
To search the remaining output of the show command, use the following command at the --More-- prompt:
/regular-expression
To filter the remaining output of the show command, use one of the following commands at the --More-- prompt:
-regular-expression
+regular-expressionSyntax Description
Command Mode
EXEC
Usage Guidelines
This modification to show commands first appeared in Cisco IOS Release 12.0(1)T.
The regular-expression argument is case sensitive and allows for complex matching requirements.
You can specify a new search at every --More-- prompt.
Note
Because prior output is not saved, you cannot search or filter backward through prior output.
When output volume is large, the search can produce long lists of output. To interrupt this output, press Ctrl-^.
Note
Sample Display
The following is partial sample output of the show interface | begin command that begins unfiltered output with the first line that contains the regular expression "Ethernet." At the --More-- prompt, the user specifies a filter to include only the lines that contain the regular expression "Serial."
router# show interface | begin EthernetEthernet0 is up, line protocol is upHardware is Lance, address is 0060.837c.6399 (bia 0060.837c.6399)Description: ip address is 172.1.2.14 255.255.255.0Internet address is 172.1.2.14/24...0 lost carrier, 0 no carrier0 output buffer failures, 0 output buffers swapped out--More--+Serialfiltering...Serial1 is up, line protocol is upSerial2 is up, line protocol is upSerial3 is up, line protocol is downSerial4 is down, line protocol is downSerial5 is up, line protocol is upSerial6 is up, line protocol is upSerial7 is up, line protocol is upRelated Commands
more begin
more exclude
more include
show exclude
show includeshow exclude
To filter show command output so that it excludes lines that contain a particular regular expression, use the show exclude command in EXEC mode.
show any-command | exclude regular-expression
To search the remaining output of the show command, use the following command at a --More-- prompt:
/regular-expression
Syntax Description
Command Mode
EXEC
Usage Guidelines
This modification to show commands first appeared in Cisco IOS Release 12.0(1)T.
The regular-expression argument is case sensitive and allows for complex matching requirements.
You can specify a new search at every --More-- prompt.
Note
Because prior output is not saved, you cannot search or filter backward through prior output.
When output volume is large, the search can produce long lists of output. To interrupt this output, press Ctrl-^.
Note
Sample Display
The following is partial sample output of the show buffers | exclude command. It excludes lines that contain the regular expression "0 misses." At the --More-- prompt, the user searches for the regular expression "Serial0." This continues the filtered output with the first line that contains "Serial0."
router# show buffers | exclude 0 missesBuffer elements:398 in free list (500 max allowed)Public buffer pools:Small buffers, 104 bytes (total 50, permanent 50):50 in free list (20 min, 150 max allowed)551 hits, 3 misses, 0 trims, 0 createdBig buffers, 1524 bytes (total 50, permanent 50):49 in free list (5 min, 150 max allowed)Very Big buffers, 4520 bytes (total 10, permanent 10):...Huge buffers, 18024 bytes (total 0 permanent 0):0 in free list (0 min, 4 max allowed)--More--/Serial0filtering...Serial0 buffers, 1543 bytes (total 64, permanent 64):16 in free list (0 min, 64 max allowed)48 hits, 0 fallbacksRelated Commands
more begin
more exclude
more include
show begin
show includeshow include
To filter show command output so that it only displays lines that contain a particular regular expression, use the show include command in EXEC mode.
show any-command | include regular-expression
To search the remaining output of the show command, use the following command at the --More-- prompt:
/regular-expression
Syntax Description
Command Mode
EXEC
Usage Guidelines
This modification to show commands first appeared in Cisco IOS Release 12.0(1)T.
The regular-expression argument is case sensitive and allows for complex matching requirements.
You can specify a new search at every --More-- prompt.
Note
Because prior output is not saved, you cannot search or filter backward through prior output.
When output volume is large, the search can produce long lists of output. To interrupt this output, press Ctrl-^.
Note
Sample Display
The following is partial sample output of the show interface | include command. It only displays lines that contain the regular expression "( is )." The parenthesis force the inclusion of the spaces before and after "is." This ensures that only lines containing "is" with a space both before and after it will be included in the output. This excludes lines with words like "disconnect."
router# show interface | include ( is )ATM0 is administratively down, line protocol is downHardware is ATMizer BX-50Dialer1 is up (spoofing), line protocol is up (spoofing)Hardware is UnknownDTR is pulsed for 1 seconds on resetEthernet0 is up, line protocol is upHardware is Lance, address is 0060.837c.6399 (bia 0060.837c.6399)Internet address is 172.21.53.199/24Ethernet1 is up, line protocol is upHardware is Lance, address is 0060.837c.639c (bia 0060.837c.639c)Internet address is 5.5.5.99/24Serial0:0 is down, line protocol is downHardware is DSX1...--More--At the --More-- prompt, the user searches for the regular expression "Serial0:13." This continues filtered output with the first line that contains "Serial0:13."
/Serial0:13filtering...Serial0:13 is down, line protocol is downHardware is DSX1Internet address is 11.0.0.2/80 output errors, 0 collisions, 2 interface resetsTimeslot(s) Used:14, Transmitter delay is 0 flagsRelated Commands
more begin
more exclude
more include
show begin
show exclude
