Foundation Rules

Overview

Foundation rules are a more modern way to augment application processing of devices, events, flows, topology objects, and collection of metrics. Foundation rules provide support for multiple vendors out-of-the-box without the need for separate integration rule packages. Unlike Classic rules, they are automatically updated in the default read-write rules branch. Customizations must be made in a supported override manner detailed below.

New installations will automatically use the Foundation rules. Existing installations that are updated will receive the Foundation rules, but they may not be activated until a few manual changes are made.

Getting Started with Foundation Rules

Foundation rules are installed in a folder called _vendor in each rules packages that has a compatible application. Each file has a .foundationrules extension. The base.load file looks for all .foundationrules files and loads them in alphanumeric order. The base.rules file then uses these rules by checking for the existence of a matching value, and calling the rules defined.

Foundation rule files may contain more than one entry. The key to the foundationrules hash depends on the type of application used (for example, defined as the Trap OID for the Trap Aggregator), and the value is an anonymous function that will be called if the key matches the application's criteria.

Using Rules

Event Trap Aggregator

If you are updating an existing install and want to start using Foundation rules, you need to make two changes.

  1. Copy the section in the base.load file from the read-only (RO_LOCKED) branch to the base.load file in the default or other branch used.

    #===========================================================================
# Foundation Rules
#===========================================================================
$Log->Message('INFO', 'Load Rules -> Foundation Rules');

my @foundationRuleFiles = File::Find::Rule->file()->name('*.foundationrules')->in("$ConfigBranchDir/collection/event/trap");
foreach my $foundationRuleFile (sort @foundationRuleFiles) {
    $Log->Message('INFO', 'Load Rules -> Foundation Rules loaded -> ' . $foundationRuleFile);
    do $foundationRuleFile;
}
#---------------------------------------------------------------------------

  2. Copy the section in the base.rules file from the read-only (RO_LOCKED) branch to the base.rules file in the default or other branch used:

    if (exists $foundationrules{$trapoid}) {
    $Log->Message('DEBUG', "Running Foundation Rule function for $trapoid");

    $foundationrules{$trapoid}->();

    $Event->{'EventKey'} = join('+', $Event->{'Node'}, $Event->{'SubNode'}, $Event->{'EventType'}, $Event->{'EventCategory'});
}

  3. Restart or reload the application.

Metric SNMP Polling

If you are updating an existing install and want to start using Foundation rules, you need to make two changes.

  1. Copy the section in the base.load file from the read-only (RO_LOCKED) branch to the base.load file in the default or other branch used.

    #===========================================================================
# Foundation Rules
#===========================================================================
$Log->Message('INFO', 'Load Rules -> Foundation Rules');

my @foundationruleFiles = File::Find::Rule->file()->name('*.foundationrules')->in("$ConfigBranchDir/collection/metric/snmp");
foreach my $foundationruleFile (sort @foundationruleFiles) {
    $Log->Message('INFO', 'Load Rules -> Foundation Rules loaded -> ' . $foundationruleFile);
    # "do" can happen more than once per app run, so it supports reload where require doesn't
    do $foundationruleFile;
}
#---------------------------------------------------------------------------

  2. Copy the section in the base.rules file from the read-only (RO_LOCKED) branch to the base.rules file in the default or other branch used:

    # if this vendor has specific rules, run them.
# - Each vendor can have >1 EnterpriseObjectID (HP has both hp and compaq)
# - A given Vendor's EnterpriseObjectID doesn't have to map to vendor-specific rules (Fireeye runs ucdavis rules)
# - A given Vendor's EnterpriseObjectID can point to multiple sets of rules (rbt runs both rbt and ucdavis)
my @vendors = exists($foundationmap{$EnterpriseObjectID}) ? @{$foundationmap{$EnterpriseObjectID}} : ();

# We ALWAYS run the mib-2 rules, whether or not there were more specific rules to run
push(@vendors, 'mib-2');

$Log->Message('INFO', "Base Rules -> [$DeviceInfo] -> Polling using Foundation Rules ($EnterpriseObjectID, " . join(', ', @vendors) . ')');
foreach my $vendor (@vendors) {
    $Log->Message('INFO', "Base Rules -> [$DeviceInfo] -> Executing $vendor rules");
    $Log->Message('INFO', "Base Rules -> [$DeviceInfo] -> " . Dumper $foundationrules);
    $foundationrules{$vendor}->({
        Session      => $Session,
        DeviceHash   => $DeviceHash,
        PollHash     => $PollHash,
        AppConfig    => $AppConfig,
        MetricHash   => $MetricHash,
        DataQueue    => $DataQueue,
        RulesDBH     => $RulesDBH,
        Log          => $Log,
    });
    $Log->Message('INFO', "Base Rules -> [$DeviceInfo] -> Finished $vendor rules");
}

  3. Restart or reload the application.

Overrides

Foundation rules may be updated or added each time a rules package is updated. To prevent customizations from being deleted, the override pattern allows these customizations to remain in place. The default Foundation rules are in a directory _vendor to allow them to be loaded first. Any other custom .foundationrules files will be loaded afterward. This allows customizations to override the defaults even when those defaults change.

Trap

Example of how to change the severity of an ifDown trap to critical.

SNMP Polling

Example of adding a new enterprise OID to call the ucdavis foundation rules.

Hybrid Rules

Classic rules and Foundation rules can be used at the same time. If the same vendor or capability is defined in both, there can be a problem with priority and these conflicts should be resolved.

Disable Classic Traps

Example of how to disable Classic rules for Cisco.

Disable Foundation Traps

Example of how to disable Foundation rules for Cisco.

Disable Classic SNMP Polling

Example of how to disable the Classic rules for Cisco.

Disable Foundation SNMP Polling

Example of how to disable Foundation rules for Cisco.