Skip to content
Guides & References

Check if a line is there or not (must contain)

Learn how must contain and must not contain checks work: is a line in the config, or is it not? See how each rConfig method compares text.

Policy LibraryUpdated
On this page

Check if a line is there or not (must contain)

Most rules ask one simple question. Is this line in the config? Or is it not? These are called must contain and must not contain checks.

rConfig has a few ways to check. They do not all read text the same way. This page shows how each one works, with the real result rConfig gives.

All the examples on this page use this part of an IOS-XE config (sanitised from tests/storage/test_router_showrun.txt):

hostname router1
!
aaa new-model
aaa authentication login default local
aaa session-id common
!
ip domain name example.com
!
no ip subnet-zero
!
interface GigabitEthernet1
ip address dhcp
negotiation auto
!
snmp-server host 192.0.2.1 EXAMPLECOMM
snmp-server host 192.0.2.2 EXAMPLECOMM10
snmp-server host 192.0.2.2 EXAMPLECOMM12xxxxxxx
snmp-server host 192.0.2.3 EXAMPLECOMM20
snmp-server host 192.0.2.4 EXAMPLECOMM30
!
line con 0
logging synchronous
stopbits 1
line vty 0 4
transport input telnet ssh
!
end

How each method compares text

Method Compares against Case Passes when
must_match_single_string Each whole line, trimmed Sensitive One line equals the body exactly
must_not_match_single_string Each whole line, trimmed, runs of whitespace collapsed Insensitive No line equals the body
must_match_all_from_array The whole config as one block of text Sensitive Every body line appears somewhere, even inside a longer line
can_match_any_from_array The whole config as one block of text Sensitive At least one body line appears somewhere
must_not_match_all_from_array The whole config as one block of text Sensitive Not all body lines appear. See avoiding false positives

The difference between “whole line” and “somewhere in the config” matters more than anything else on this page.


One exact line: must_match_single_string

The body must equal a complete config line. Leading and trailing spaces are ignored on both sides; nothing else is.

// Trap host 192.0.2.2 uses community EXAMPLECOMM10
#[must_match_single_string]
snmp-server host 192.0.2.2 EXAMPLECOMM10
// Trap host 192.0.2.2 uses community EXAMPLECOMM12
#[must_match_single_string]
snmp-server host 192.0.2.2 EXAMPLECOMM12
// Trap host 192.0.2.2 uses community EXAMPLECOMM100
#[must_match_single_string]
snmp-server host 192.0.2.2 EXAMPLECOMM100
// Partial line
#[must_match_single_string]
interface G
Rule Result Why
...EXAMPLECOMM10 pass The line exists exactly.
...EXAMPLECOMM12 fail The config line is ...EXAMPLECOMM12xxxxxxx. A prefix is not a match.
...EXAMPLECOMM100 fail No such line.
interface G fail Part of a line is not a match.

Source: PolicyMethodsTest::test_must_match_single_string_tests1 and test_must_match_single_string_tests2_with_partial_string_fails. Minimum version 8.0.0.


One forbidden line: must_not_match_single_string

The body must not equal any config line. This method is more forgiving than its positive twin: it ignores case and treats any run of spaces as one space, as well as ignoring leading indentation.

// No DHCP relay to 198.51.100.31
#[must_not_match_single_string]
ip dhcp relay address 198.51.100.31
// No DHCP relay to 198.51.100.99
#[must_not_match_single_string]
ip dhcp relay address 198.51.100.99

Against this config:

hsrp 14
preempt delay minimum 100
priority 120
ip 192.0.2.1
ip dhcp relay address 198.51.100.31
ip dhcp relay address 203.0.113.64
Rule Result Why
Relay to 198.51.100.31 fail The indented line matches once trimmed.
Relay to 198.51.100.99 pass No such line.

Case and spacing differences still match:

// BGP feature is not enabled
#[must_not_match_single_string]
FEATURE BGP
// OSPF feature is not enabled
#[must_not_match_single_string]
feature ospf
feature bgp
router bgp 65000
neighbor 198.51.100.1 remote-as 65001
Rule Result Why
FEATURE BGP fail Matches feature bgp after lowercasing and collapsing spaces.
feature ospf pass No such line.

Source: MustNotMatchSingleStringCustomerTest. Minimum version 8.0.0.


Several lines: the array methods

A body with more than one line is a list. The array methods look for each list item anywhere in the config text, so an item can match part of a longer line.

// At least one of these lines is present
#[can_match_any_from_array]
snmp-server host 192.0.2.2 EXAMPLECOMM10
snmp-server host 192.0.2.1 EXAMPLECOMM310
aaa session-id1
// At least one of these lines is present (none are)
#[can_match_any_from_array]
snmp-server host 192.0.2.1 EXAMPLECOMM110
snmp-server host 192.0.2.1 EXAMPLECOMM310
aaa session-id1
// Every one of these lines is present
#[must_match_all_from_array]
snmp-server host 192.0.2.2 EXAMPLECOMM10
snmp-server host 192.0.2.4 EXAMPLECOMM30
aaa session-id
no ip subnet-zero
ip domain name example.com
line vty 0 4
// Every one of these lines is present (one is not)
#[must_match_all_from_array]
snmp-server host 192.0.2.2 EXAMPLECOMM10
snmp-server host 192.0.2.4 EXAMPLECOMM30
aaa session-id
no ip subnet-zero
ip domain name example.com
line vty 0 5
// Not all of these lines are present (none are)
#[must_not_match_all_from_array]
snmp-server host 192.0.2.2 EXAMPLECOMM100
snmp-server host 192.0.2.4 EXAMPLECOMM300
aaa session-id0
no ip subnet-zero0
ip domain name example.com0
line vty 0 40
// Not all of these lines are present (all are)
#[must_not_match_all_from_array]
snmp-server host 192.0.2.2 EXAMPLECOMM10
snmp-server host 192.0.2.4 EXAMPLECOMM30
aaa session-id
no ip subnet-zero
ip domain name example.com
line vty 0 4

Against the IOS-XE excerpt at the top of the page:

Rule Result Why
can_match_any, one present pass snmp-server host 192.0.2.2 EXAMPLECOMM10 is present.
can_match_any, none present fail No item appears.
must_match_all, all present pass Every item appears. aaa session-id matches inside aaa session-id common.
must_match_all, one missing fail line vty 0 5 does not appear.
must_not_match_all, none present pass Not every item appears.
must_not_match_all, all present fail Every item appears.

Source: PolicyMethodsTest::test_can_match_any_from_array_tests, test_must_match_all_from_array_tests and test_must_not_match_all_from_array_tests. Minimum version 8.0.0.

The third row is the substring behaviour in action: aaa session-id is not a line in the config, but it is part of one. That is useful when you want “starts with”, and a source of false passes when you do not. Avoiding false positives covers both array traps.


Choosing between them

Exact line required: must_match_single_string. Line forbidden: must_not_match_single_string for a fixed line, wildcard_must_not_match_single_string when part of it varies. Several lines required: must_match_all_from_array, accepting that items match inside longer lines. One of several alternatives: can_match_any_from_array. Lines must sit inside one section: use a section-scoped check instead.

Type to search.