Foundation Rules¶
Overview¶
Foundation rules are a new and 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 after this date will automatically use the Foundation rules. Existing installations that are updated will receive the Foundation rules, but they will 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.
-
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; } #--------------------------------------------------------------------------- -
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'}); } -
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.
-
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; } #--------------------------------------------------------------------------- -
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"); } -
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.
-
Create a custom/ietf.foundationrules file with the following contents:
$foundationrules{'1.3.6.1.6.3.1.1.5.3'} = sub { #==========================================================================# # IF-MIB::linkDown #==========================================================================# # DESCRIPTION # A linkDown trap signifies that the SNMP entity, acting in # an agent role, has detected that the ifOperStatus object for # one of its communication links is about to enter the down # state from some other state (but not from the notPresent # state). This other state is indicated by the included value # of ifOperStatus. # # VARIABLES # 1. ifIndex (INTEGER32) # A unique value, greater than zero, for each interface. It # is recommended that values are assigned contiguously # starting from 1. The value for each interface sub-layer # must remain constant at least from one re-initialization of # the entity's network management system to the next re- # initialization. # 2. ifAdminStatus (INTEGER, ENUM) # The desired state of the interface. The testing(3) state # indicates that no operational packets can be passed. When a # managed system initializes, all interfaces start with # ifAdminStatus in the down(2) state. As a result of either # explicit management action or per configuration information # retained by the managed system, ifAdminStatus is then # changed to either the up(1) or testing(3) states (or remains # in the down(2) state). # 3. ifOperStatus (INTEGER, ENUM) # The current operational state of the interface. The # testing(3) state indicates that no operational packets can # be passed. If ifAdminStatus is down(2) then ifOperStatus # should be down(2). If ifAdminStatus is changed to up(1) # then ifOperStatus should change to up(1) if the interface is # ready to transmit and receive network traffic; it should # change to dormant(5) if the interface is waiting for # external actions (such as a serial line waiting for an # incoming connection); it should remain in the down(2) state # if and only if there is a fault that prevents it from going # to the up(1) state; it should remain in the notPresent(6) # state if the interface has missing (typically, hardware) # components. #--------------------------------------------------------------------------# my %ifAdminStatusEnums = ( '1' => 'up', '2' => 'down', '3' => 'testing', ); $v2 = $ifAdminStatusEnums{$v2} // $v2; my %ifOperStatusEnums = ( '1' => 'up', '2' => 'down', '3' => 'testing', '4' => 'unknown', '5' => 'dormant', '6' => 'notPresent', '7' => 'lowerLayerDown', ); $v3 = $ifOperStatusEnums{$v3} // $v3; $Event->{'AlarmGroup'} = "linkUpDown"; $Event->{'AlarmType'} = 2; $Event->{'Severity'} = 5; # <--------------- This is the new severity defined $Event->{'SubAlarmGroup'} = "ifIndex: $v1"; $Event->{'SubMethod'} = "IF-MIB"; $Event->{'Summary'} = "Link down on ifIndex: $v1"; };
SNMP Polling¶
Example of adding a new enterprise OID to call the ucdavis foundation rules.
-
Create a custom/newvendor.foundationrules file with the following contents:
$foundationmap{'1.3.6.1.4.1.999999'} = [ 'ucdavis' ];
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.
-
Update collection/event/trap/base.rules in the default or other branch used, and comment out:
##################################################### # Cisco Default Include Trap Rules ##################################################### #if ($enterprise =~ /^1\.3\.6\.1\.4\.1\.9\b/) { # $Event->{'SubMethod'} = "Cisco Traps"; # $Log->Message('DEBUG', "Using Cisco Trap Rules - [$enterprise] - $specific - $generic"); # CiscoRules(); #} ##################################################### -
Optionally these lines could be removed completely and then delete the line from collection/event/trap/base.includes:
CiscoRules,integrationCiscoNetwork/trap/vendor/cisco.include.rules
Disable Foundation Traps¶
Example of how to disable Foundation rules for Cisco.
-
Update collection/event/trap/base.load in the default or other branch used:
my @foundationRuleFiles = File::Find::Rule->file()->name('*.foundationrules')->in("$ConfigBranchDir/collection/event/trap"); foreach my $foundationRuleFile (sort @foundationRuleFiles) { ### This is the new exclusion if ($foundationRuleFile ne 'cisco.foundationrules') { $Log->Message('INFO', 'Load Rules -> Foundation Rules loaded -> ' . $foundationRuleFile); do $foundationRuleFile; } } #---------------------------------------------------------------------------
Disable Classic SNMP Polling¶
Example of how to disable the Classic rules for Cisco.
-
Update collection/metric/snmp/base.rules in the default or other branch used, and comment out:
######################################## # Default Cisco SNMP Integration Polling Rules ######################################## #if ($SysObjectID =~ /^1\.3\.6\.1\.4\.1\.9\b/) { # Cisco # $Log->Message('INFO', "Base Rules -> [$DeviceInfo] -> Polling using Cisco Rules"); # CiscoHealthRules(); # CiscoIPSLARules(); # ##CiscoCoSRules(); # CiscoCBQOSBitRateRules(); #} ######################################## -
Optionally these lines could be removed completely and then delete these lines from collection/metric/snmp/base.includes
CiscoHealthRules,integrationCiscoNetwork/snmp/vendor/cisco.device-health.include.rules CiscoIPSLARules,integrationCiscoNetwork/snmp/vendor/cisco.ipsla.include.rules #CiscoCoSRules,integrationCiscoNetwork/snmp/vendor/cisco.cos.include.rules CiscoCBQOSBitRateRules,integrationCiscoNetwork/snmp/vendor/cisco.cos.include.rules
Disable Foundation SNMP Polling¶
Example of how to disable Foundation rules for Cisco.
-
Update collection/metric/snmp/base.load in the default or other branch used:
# We ALWAYS run the mib-2 rules, whether or not there were more specific rules to run push(@vendors, 'mib-2'); ### This is the new exclusion if ($EnterpriseObjectID eq '1.3.6.1.4.1.9') { @vendors = (); } $Log->Message('INFO', "Base Rules -> [$DeviceInfo] -> Polling using Foundation Rules ($EnterpriseObjectID, " . join(', ', @vendors) . ')');