Cisco IOS Pipe Function: Filtering Command Output
Learn how to use the Cisco IOS pipe character with include, exclude, begin, and section filters to search and review CLI command output.
The Cisco IOS pipe character, |, invokes an output filter after a command. It is especially useful with long show commands because you can display only relevant lines or start viewing at a useful point.
Pipe filtering changes what is displayed in the terminal. It does not change the running configuration, startup configuration, routing table, interface state, or packet-forwarding behavior.
Prerequisites
You should be comfortable with Cisco IOS command modes, basic show commands, interface status, configuration output, and basic routing and switching terms. A review of the OSI reference model can help with interpreting protocol and interface information.
Pipe Command Syntax
The general structure is:
command | filter-option expression- Source command: The command that produces output, such as
show running-configorshow ip route. - Pipe character: The vertical bar,
|, tells IOS to apply an output filter. - Filter option: The operation, such as
include,exclude,begin, orsection. - Expression: The text or regular-expression pattern used to select output.
For example:
show ip interface brief | include upUnlike shell piping in Linux or other operating systems, IOS does not normally pass one command's output as input to a second arbitrary command. The IOS pipe applies one of the filtering operations supported by the command and platform.
Cisco IOS Pipe Filter Options
| Filter option | What it displays | Typical use | Example |
|---|---|---|---|
include | Lines matching an expression | Find individual status, address, route, or configuration lines | show ip interface brief | include up |
exclude | Lines that do not match an expression | Remove repetitive or known-irrelevant lines | show ip interface brief | exclude administratively down |
begin | The first matching line and all later output | Jump to a later portion of a long display | show running-config | begin interface |
section | A matching configuration heading and associated block, where supported | Review an interface, routing, line, or access-list section | show running-config | section interface GigabitEthernet0/1 |
The include Filter
include displays only lines containing the supplied string or matching regular expression. It is useful for fast status scans.
Interface and protocol status
show ip interface brief | include upThis displays lines containing up. It can quickly identify interfaces whose status or protocol field contains that word. Because the pattern is not very specific, inspect the unfiltered command when the distinction between administratively up, line protocol up, and other text matters.
show interfaces | include protocol is|input errors|output errorsThis uses alternation to select interface state and error-summary lines in one view. It is a useful first pass before examining a particular interface in detail.
Routes, VLANs, neighbors, and logs
show ip route | include Gateway|0.0.0.0show vlan brief | include activeshow cdp neighbors detail | include Device ID|IP addressshow logging | include LINK|LINEPROTO
These examples select default-route or gateway-related text, active VLAN entries, important CDP neighbor fields, and common interface link events. The exact wording varies by platform and release.
Matching is generally case-sensitive. If a search returns nothing, inspect the command without a pipe and copy the capitalization and wording shown by the device.
The exclude Filter
exclude is the inverse of include: it suppresses lines containing the expression and displays the remaining lines.
show ip interface brief | exclude administratively downThis removes interfaces that are administratively disabled from the displayed view. It can reduce noise when reviewing active or potentially problematic interfaces, but it can also hide information needed during diagnosis. Always compare with the original output when troubleshooting.
The begin Filter
begin starts displaying output at the first line that matches the expression. Every subsequent line remains visible.
show running-config | begin router ospfshow running-config | begin interface
If the first matching line is router ospf, IOS displays that line and everything after it. This differs from include, which displays only individual matching lines. It also differs from section, which is intended to isolate a configuration block where supported.
The section Filter
section is commonly used with configuration output. It displays a matching heading together with its associated subordinate configuration lines when the platform supports that behavior.
show running-config | section interface GigabitEthernet0/1show running-config | section router ospfshow running-config | section line vtyshow running-config | section access-list
Typical uses include reviewing an interface stanza, routing protocol configuration, line settings, or access-list-related configuration. Section behavior and availability vary by IOS platform and release, so use contextual help before relying on it.
Regular Expressions and Match Patterns
A regular expression is a pattern language for matching text. IOS pipe filters use regular-expression features rather than treating every expression as plain words. Begin with literal text, then add metacharacters only when they improve accuracy.
| Pattern element | Meaning | Example pattern | Matching behavior |
|---|---|---|---|
| Literal text | Matches the characters supplied | input errors | Matches lines containing that phrase |
^ beginning-of-line anchor | Requires a match at the start of a line | ^ntp | Matches global lines beginning with ntp |
$ end-of-line anchor | Requires a match at the end of a line | up$ | Matches lines ending in up |
| alternation | Matches one pattern or another | LINK|LINEPROTO | Matches either event keyword |
[] character class | Matches one character from the class | GigabitEthernet[0-9] | Matches a digit in the specified position |
() grouping | Groups pattern components | (up|down) | Groups alternatives for a larger expression |
* repetition | Repeats the preceding element zero or more times | ab*c | Matches ac, abc, and similar forms |
| Escape character | Causes a metacharacter to be treated literally where supported | \. | Matches a literal period instead of regex punctuation |
Anchors are particularly useful for configuration searches:
show running-config | include ^hostnameshow running-config | include ^ntp
The first command finds a global hostname command. The second finds lines that begin with the ntp keyword, such as NTP configuration lines. Without ^, a match could occur in the middle of an unrelated line.
Alternation can combine related searches:
show ip route | include ^S|^O|^Dshow cdp neighbors detail | include Device ID|IP address
In the route example, the patterns select lines beginning with common route-source codes. Adjust the codes to the routing protocols and output format in your environment. In the CDP example, either field is selected.
Metacharacters have special meanings. A period, a bracket, a parenthesis, a vertical bar, an asterisk, and anchors should not be assumed to be ordinary text. Escape a character when you need its literal meaning and verify the syntax with the device's contextual help.
Filtering Common Verification Commands
| Command | Example filter | Verification goal |
|---|---|---|
show running-config | | include ^hostname | Find a global hostname line |
show ip interface brief | | include up | Scan interface status lines |
show interfaces | | include input errors|output errors | Locate error summaries |
show ip route | | include Gateway|0.0.0.0 | Find gateway or default-route information |
show vlan brief | | include active | Focus on active VLAN entries |
show cdp neighbors detail | | include Device ID|IP address | Identify neighbor names and addresses |
show logging | | include LINK|LINEPROTO | Find interface link and protocol events |
Filtering is a starting point, not a replacement for a full verification command. For example, an error line can identify an interface for deeper inspection with show interfaces GigabitEthernet0/1.
Using Pipes During Configuration Review
The running configuration is the active configuration currently used by the device. Pipes can help locate configuration, but they do not interpret dependencies or prove that a feature is operating correctly.
Common configuration searches
show running-config | section interface GigabitEthernet0/1show running-config | section router ospfshow running-config | include neighborshow running-config | include access-listshow running-config | include usernameshow running-config | include ^snmpshow running-config | include ^ntpshow running-config | section line
These searches can find an interface stanza, routing-process configuration, neighbor statements, access-list entries, username definitions, SNMP settings, NTP servers, and line configuration. Use a more precise expression when a short word could match unrelated commands.
Searching configuration output has limits. A missing line does not always mean a feature is inactive, and a present line does not prove that the feature has formed neighbors, installed routes, or exchanged traffic. Use feature-specific commands such as show ip ospf neighbor, show ip route, or show ntp status to verify operation. See the lessons on configuring OSPF and configuring NTP on a Cisco device for feature-specific verification.
Command-Line Help and Platform Differences
Use the question mark to discover options supported by the current device:
show ?show running-config | ?
show ? lists available show commands. The second command displays pipe options accepted for that output on the current platform and software release.
Routers, switches, IOS, IOS XE, Packet Tracer images, and different releases may not expose identical filters. Do not assume that documentation for one platform applies to another. If section is unavailable, use a supported filter such as begin, a feature-specific show command, or unfiltered output.
Pipe Filter Selection Guide
| Administrative goal | Recommended filter | Why | Example show command |
|---|---|---|---|
| Find individual matching lines | include | Displays only matching lines | show logging | include LINK |
| Remove unwanted lines | exclude | Suppresses lines matching a known pattern | show ip interface brief | exclude administratively down |
| Jump to a later portion of output | begin | Retains the first match and all later lines | show running-config | begin router |
| Review a configuration block | section | Shows a heading and related block where supported | show running-config | section interface |
Operational Limitations and Best Practices
- A pipe expression works only on output generated by a command. It does not execute independently and does not modify device state.
- Start with broad output when the expected wording is uncertain. Inspect the exact output, then refine the expression.
- Prefer precise patterns and anchors to avoid accidental partial matches.
- Be cautious with
exclude; hiding warnings can make an outage harder to diagnose. - Validate filtered results with the unfiltered command before making a configuration or operational decision.
- Use feature-specific show commands when you need operational state rather than a text search of configuration.
Troubleshooting Pipe Filters
No output appears
Likely causes include capitalization differences, different device wording, an overly restrictive expression, or using the wrong show command. Run the command without a pipe, inspect the exact text, try a shorter literal expression, and then refine it.
show ip interface briefshow ip interface brief | include up
An entire interface block was expected, but only one line appeared
This usually means include was used instead of section. Try:
show running-config | section interface GigabitEthernet0/1If the platform does not support section, use begin for a broader view and identify where the next configuration section begins, or use a feature-specific show command.
Relevant outage information is hidden
A broad exclude pattern may have removed warnings or state lines. Compare the filtered output with the original command and use a targeted include expression or more exact pattern.
A regular expression matches unexpected text
A metacharacter may be acting as an operator, a short pattern may match part of unrelated words, or alternation may not be grouped as intended. Test one component at a time, add anchors, escape literal special characters where required, and validate against unfiltered output.
A documented option is unavailable
The device may use a different IOS release, platform, image, or simulator implementation. Run contextual help with ?, choose a supported filter, or use a more specific show command.
Quick Practice
- Use
show ip interface brief | include upto perform a quick interface-status scan. - Use
show running-config | section interface GigabitEthernet0/1to review one interface stanza. - Use
show running-config | begin router ospfto compare a broad starting point with section filtering. - Use
show ip route | include Gateway|0.0.0.0to search for gateway and default-route text. - Run each command once without a pipe and compare the complete output with the filtered result.