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

On the Add Rule, Edit Rule, or Copy Rule page, click the Grammar tab.
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.
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). BMC 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.
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.

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.

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. BMC Network Automation can correct violations (that is, Remediate).
- Lines: Enter one or more lines. Do not use any regular expressions in the lines. BMC 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. BMC Network Automation substitutes these values when performing the compliance check. For more information, see Using substitution parameters in rules.

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

Option	Description
AND	(For Lines and Patterns only) Controls how the items entered in the Lines or Patterns field are handled when BMC Network Automation checks for subject matches in the configuration. If you select the AND option, all of the items must be in the configuration for a subject match to be found. See Subject field compliance scenarios for more information.
OR	(For Lines and Patterns only) Controls how the items entered in the Lines or Patterns field are handled when BMC Network Automation checks for subject matches in the configuration. If you select the OR option, when any of the items appear in the configuration, a subject match is found. See Subject field compliance scenarios for more information. Note: When you select the OR option, the Contiguous and Ordered options are not available.
Case Sensitive	The subject is sensitive to upper and lower case.
Contiguous	The lines/patterns have no other line/pattern interleaved. Note: This option is not available when you select the OR option.
Ordered	The lines/patterns must be in consecutive order. Note: This option is not available when you select the OR option.
Ignore Whitespace	Ignore leading command line white space. When this option is selected (the default), any leading white space in the subject line or the correction (whichever is being used to make the correction for this rule) is stripped off, and BMC Network Automation adds white space to match the indentation level of the line before the insertion point. If the insertion is at the end of a block, the inserted line has the same number of spaces as the last line in the block, which could be an inner line of a sub-block. This might produce the right result. If the last line is in a sub-block and the lines being added belong to the outer block, then the inserted lines belong to the sub-block and the merge script shows the correction inside all the nesting. When you clear this option, BMC Network Automation inserts the correction exactly as you entered it. The insertion is at the end of the block, but the indentation that you provide determines whether the correction belongs to the outer block or to an inner block. So it is possible to produce a correct compliant configuration with the description line correctly indented, even below an inner sub-block. Ensure this option is cleared whenever dealing with block contents. Supply leading white spaces in the subject line or correction.
Correct Missing	Use the correction stated when performing remediation. Depending on the type of corrective action, these corrections might be ignored. They are ignored by any corrective action that does not compute a configuration complying with this rule. That is, corrections are ignored when the corrective action is not Deploy to Active or Deploy to Stored, or when these corrective actions use a template that provides the needed corrections.
Force All Corrections	(For Patterns only) When this option is not enabled, the number of patterns must match the number of corrections; when a pattern is violated, the corresponding correction line is applied to the configuration. When this option is enabled, the number of patterns and corrections need not match; every correction line is applied to the configuration when any of the patterns is violated. When the Force All Corrections option is enabled for a rule and the Incremental Merge option is enabled for an associated Deploy to Active job, the rollback script is generated with the exact set of device commands specified in the Corrections field when making a device compliant. Prior to this change, the device commands in the rollback script were slightly modified during deploy to active, if the device supported smart merge. In addition, when a device is made compliant with a rule set, and all the rules in the rule set have the Force All Corrections option enabled, those corrections appear in the order in which the rules appear within the rule set, typically ordered by rule name. If a rule set has rules with a mix of forced and non-forced corrections, the forced corrections appear first in the rollback script followed by the non-forced corrections. If the domain is comprised of domain blocks, the block header is output first, followed by the subject corrections. For example, given the following rule for a Cisco IOS device: Domain Block Begin: `line vty .` Domain Block End:* `^\S+` Subject patterns: `^exec-timeout 2 0` Subject corrections: `default exec-timeout` `exec-timeout 2 0` If the configuration has a matching domain, for example, `line vty 0 4`, and the configuration does not have any matching subject patterns in the specified domain, the rollback script is as follows: `line vty 0 4` `default exec-timeout` `exec-timeout 2 0` This is exactly the same as the one specified in subject corrections along with the block header. Note: If the Force All Corrections option is not enabled, and the device supports an incremental merge, the device commands in the rollback script might not be exactly the same as subject corrections. If you select the Full merge option, the corrections are applied to the configuration based on the order of the rules in the rule set, typically ordered by the name of rule.

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
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.

Defining rule grammar

To define rule grammar

Comments