Defining rule grammar

A grammar specifies how to search a configuration file for the presence or absence of a line, multiple lines, pattern or multiple patterns. The grammar specifies where to search (Domain) and what to search for (Subject). During rule configuration, you configure rule grammar on the Grammar tab.

You can use regular expressions when specifying a pattern in a rule grammar. For more information about meta characters used in regular expressions for pattern matching, see Grammar-field-metacharacters.

For a list of conditions that must exist for the enforcement of rules, see Conditions-for-rule-enforcement.

For example implementations of grammar for rules, see Grammar-examples.

To define rule grammar

1. On the Add Rule, Edit Rule, or Copy Rule page, click the Grammar tab.
   
   
2. If you want to specify a trigger, specify a value in the Trigger field.
    The default trigger is None. This optional field is used to get values from the command line to be used in evaluating the rule. If multiple triggers are found, the rule is evaluated once for each trigger value.
    In the example below, the expression (\S+) extracts the extended ACL name that can later be referenced in the Subject and Domain as ${trigger.1}. Up to nine values can be extracted and referenced as ${trigger.1} ... ${trigger.9}. You can specify the Scope of where to find the trigger as Entire Configuration or Domain Region.
   
   
3. In the Domain field, specify where the subject search should begin in the configuration. The valid values are:
   • Entire configuration: Search for the subject anywhere in the configuration.
     
     
   • Selected Lines: Search for the subject in all lines matching the specified pattern.
     
     
   • Selected Blocks: Search for the subject in all blocks bounded by a Begin line/pattern and End line/pattern.
     
     
   • Selected Nested Blocks: Search for the subject in all blocks bounded by multiple begin and end lines and/or patterns. Define the block headers and footers in order from outermost to innermost. The subject and any Trigger are searched for inside the content of the innermost block.
     
     
   • OS Image Name: Audit the OS software version on devices. Set the Subject to the exact OS image name(s) (that is, Line, as in the following figure, or Lines) or the abbreviated name(s) (that is, Pattern or Patterns using regular expressions). TrueSight Network Automation audits the discovered OS image name in the device record against the rule. Note that a violation in an OS Image Name domain cannot be corrected automatically.
     
     
4. If searching for Selected Lines, Selected Blocks, or Selected Nested Blocks, you can further narrow the search, in one of the following ways:
   • Include only those lines or blocks that contain a specified pattern.
     The following example includes an interface with an IP address within a specified range:
     interface fastethernet0
     ip address 10.1.199.2
     
     

   • Ignore lines or blocks that contain a specified pattern.
     The following example ignores all interfaces that are shut down:
     interface fastethernet0
     shutdown
     
     

     Note

     If you specify both a pattern to ignore and a pattern to include, the ignore setting takes precedence.
      For example, if you have the following block:
     interface fastethernet0
      ip address 10.1.199.2
      shutdown
     !
     And you specify the following patterns to include and ignore:
     include = ^\s+ip\s+address\s+10.*.199.(1|2|10).*
     ignore = ^\s+shutdown
     
     The block is ignored, because the ignore setting takes precedence.

5. In the Domain field, select any of the following additional options for the domain criteria. These options appear based on other selections made on this page:

   Field	Description
   Case Sensitive	The selected domain search is sensitive to upper and lower case. Use this when the configuration shows that case is significant and names of things are allowed to vary just in the case.
   Ignore Comments	The selected domain search ignores comments, as defined by the device type associated with a particular device. Use this to avoid mismatching strings that are on comment lines.
   Ignore Line Breaks	The selected domain search treats the configuration as one long continuous string. Use this on data such as banners, where the same content was applied to many devices, but the lines were broken up differently.
   Distinct End Lines	The selected blocks end with a unique line paired to the begin line. Use this when the configuration shows each block matched to its own end line, such as a begin line ending in a left brace might be matched to an end line ending in a right brace. If the block needs to be removed, the paired distinct end line gets removed.
   Exclude Trigger Line	The selected domain search ignores any line that matched the trigger.
   Remove Emptied Block(s)	The entire block is to be removed if removal of the subject causes the block to become empty. Use this option when the device treats empty blocks as illegal (for example, Juniper JunOS).
   Domain Frequency	Indicates how often a domain block is expected to appear and controls deletion of excess blocks or insertion of missing blocks.

6. In the Subject field, specify what should be found (or not found) in the configuration. The Subject can be specified as a single line, multiple lines, single pattern, multiple patterns, a parsed line, or an ordered version string.
   
   • Line: Search for a single line. Do not use regular expressions in the line. TrueSight Network Automation can correct violations (that is, Remediate).
     
     
   • Lines: Enter one or more lines. Do not use any regular expressions in the lines. TrueSight Network Automation can correct violations (that is, Remediate).
     
     
   • Pattern: A single pattern that uses regular expressions. When specifying a Subject by using a Pattern, you can optionally specify the Correction for enforcing the rule during a Remediate.
     
     
   • Patterns: One or more patterns that uses regular expressions. When specifying a Subject by using Patterns, you can optionally specify the Correction for enforcing the rule during a Remediate.
     
     

   • Parsed Line: A pattern with parts that can be individually checked against specified text or numeric values. In the Line Parsing Pattern, enter a regular expression that will match a line in the configuration. Include capture groups (a part of the regular expression in parentheses) for the parts to be validated further. Then, for each capture group add a Capture Group Comparison. Each capture group can be compared against one or more text strings, or can be compared numerically against a target number.
     If the capture group specifies a number, you can compare it with a target number as follows:

     • Number Is / Is Not, Less Than the target number
     • Number Is / Is Not, Less Than or Equal To the target number
     • Number Is / Is Not, Greater Than the target number
     • Number Is / Is Not, Greater Than or Equal To the target number
     • Number Is / Is Not, Equal To the target number
     • Number Is / Is Not, Within Range (Inclusive) in From target number and To the target number.

     For example, ssh timeout (\d+) pattern shown in the following figure matches any line containing ssh timeout 60, 6060,..and so on.    

     

     If the capture group specifies text, you can compare it with one or more target strings as follows:

     • Text Matches One / Many target strings
     • Text Does Not Match One / Many target strings
     • Text Equals One / Many target strings
     • Text does Not Equal One / Many target strings

   • Ordered Version String: A pattern for extracting a version string and a version string to compare it with. In Version Capture Pattern, enter a regular expression with one capture group that specifies where the desired version string lies. Select an Operator that specifies how to compare the captured version and specify a Compare To string with the version to compare against.

      

     Note

     You can use device (${device.host}), agent (${agent.localhostIpv4Address), global (${global.ntpServer1}), and other substitution parameters in line/lines and pattern/patterns. TrueSight Network Automation substitutes these values when performing the compliance check. For more information, see Using-substitution-parameters-in-rules.

7. For the Subject field, select any of the following additional options for the search criteria:

   The [confluence_table-plus] macro is a standalone macro and it cannot be used inline. Click on this message for details.
   This macro generates standalone content. As a consequence you need to make sure to use a syntax that separates your macro from the content before and after it so that it's on a line by itself. For example in XWiki Syntax 2.0+ this means having 2 newline characters (a.k.a line breaks) separating your macro from the content before and after it.
   

8. In the Subject Frequency field, specify how often the subject should be present in the configuration. If there is a subject match, the setting of this field determines whether a compliance violation is triggered. See Subject-field-compliance-scenarios for more information. The valid values are:
   • Appears exactly once (1)
   • Appears at least once (1..*)
   • Appears at most once (0..1)
   • Do not appear
9. In the With no other lines containing pattern field, optionally restrict the subject to a specific set of commands that all begin with the same command prefix (for example, access-list, logging, aaa, ntp server). For example, the Subject specifies a list of logging lines that must appear in the configuration, and no other lines starting with logging should appear.