Inleiding

Dit document beschrijft de best practices voor de configuratie van Embedded Event Manager (EEM)-scripts op Cisco IOS® XE-apparaten.

Voorwaarden

Vereisten

Cisco raadt u aan kennis te hebben van en vertrouwd te zijn met dit onderwerp:

•  Cisco IOS en Cisco IOS XE Embedded Event Manager (EEM)

Als u nog niet bekend bent met deze functie, lees dan eerst het Overzicht van EEM-functies.

Gebruikte componenten

De informatie in dit document is gebaseerd op de volgende software- en hardware-versies:

• Cisco Catalyst 9300, 9400 en 9500 Switches
• Cisco IOS-software versie 16.x of 17.x

Opmerking: Deze scripts worden niet ondersteund door Cisco TAC en worden geleverd op een as-is basis voor educatieve doeleinden.

De informatie in dit document is gebaseerd op de apparaten in een specifieke laboratoriumomgeving. Alle apparaten die in dit document worden beschreven, hadden een opgeschoonde (standaard)configuratie. Als uw netwerk live is, moet u zorgen dat u de potentiële impact van elke opdracht begrijpt.

beste praktijken

Dit gedeelte behandelt enkele van de meest voorkomende problemen die zijn waargenomen bij het ontwerp en de implementatie van EEM-scripts. Voor aanvullende informatie over beste praktijken van de EEM, zie het document over beste praktijken van de EEM waarnaar wordt verwezen in het gedeelte Referenties.

Bevestigen dat de juiste verificatie is geïnstalleerd

Als uw apparaat AAA gebruikt, moet u ervoor zorgen dat de EEM-scripts die op het apparaat zijn geconfigureerd, zijn geconfigureerd met een AAA-gebruiker die de opdrachten in het script kan uitvoeren, of dat de autorisatie-bypass is geconfigureerd met de autorisatie-bypass in de scriptdefinitie.

Beperkingen toevoegen voor EEM-runtime en snelheidslimiet

Standaard kunnen EEM-scripts maximaal 20 seconden worden uitgevoerd. Als u een script ontwerpt dat langer duurt om uit te voeren of moet wachten tussen de uitvoering van de opdracht, geeft u een maxrun-waarde op bij de applet-gebeurtenistrigger om de standaard uitvoeringstimer te wijzigen.

Het is ook belangrijk om te overwegen hoe vaak de gebeurtenis die uw EEM-script triggert, kan worden uitgevoerd. Als u een script activeert vanuit een voorwaarde die snel in een korte tijd optreedt (bijvoorbeeld syslog-trigger voor MAC-flaps), is het belangrijk om een snelheidslimietvoorwaarde op uw EEM-script op te nemen om een buitensporig aantal uitvoeringen parallel te voorkomen en uitputting van apparaatbronnen te voorkomen.

Vermijd out-of-order uitvoering

Zoals beschreven in de documentatie van de EEM wordt de volgorde van uitvoering voor actieverklaringen bepaald door hun label (de opdracht enable voor actie 0001 cli heeft bijvoorbeeld een label van 0001). Deze labelwaarde is GEEN getal, maar eerder alfanumeriek. Acties worden gesorteerd in oplopende alfanumerieke sleutelreeks, gebruik het label argument als de sorteersleutel en ze worden uitgevoerd in deze reeks. Dit kan leiden tot onverwachte volgorde van uitvoering, gebaseerd op hoe u uw actielabels structureert.

Neem dit voorbeeld:

event manager applet test authorization bypass
event timer watchdog time 60 maxrun 60
action 13 syslog msg "You would expect to see this message first"
action 120 syslog msg "This message prints first"

Omdat 120 vóór 13 is in een alfanumerieke vergelijking, loopt dit script niet in de volgorde die je verwacht. Om dit te voorkomen, is het handig om een systeem van opvulling als volgt te gebruiken:

event manager applet test authorization bypass
event timer watchdog time 60 maxrun 60
action 0010 syslog msg "This message appears first"
action 0020 syslog msg "This message appears second"
action 0120 syslog msg "This message appears third"

Vanwege de opvulling hier, de genummerde verklaringen te evalueren in de verwachte volgorde. De toename van 10 tussen elk label maakt het mogelijk om extra instructies later in het EEM-script in te voegen waar dat nodig is, zonder dat alle volgende instructies opnieuw genummerd hoeven te worden.

Paginatie uitschakelen

EEM zoekt naar de apparaatprompt om te bepalen wanneer de opdrachtuitvoer is voltooid. Opdrachten die meer gegevens uitvoeren dan op één scherm kunnen worden weergegeven (zoals geconfigureerd door de lengte van uw terminal), kunnen voorkomen dat EEM-scripts worden voltooid (en uiteindelijk worden gedood via de maxrun-timer) omdat de apparaatprompt niet wordt weergegeven totdat alle pagina's van de uitvoer worden bekeken. Configureer term len 0 aan het begin van EEM-scripts die grote uitgangen onderzoeken.

Ontwerpscripts voor toekomstig onderhoud

Wanneer u een EEM-script ontwerpt, laat dan ruimte tussen actielabels om het gemakkelijker te maken om de EEM-scriptlogica in de toekomst bij te werken. Wanneer er voldoende hiaten beschikbaar zijn (dat wil zeggen dat twee verklaringen zoals actie 0010 en actie 0020 een gat van 9 labels achterlaten die kunnen worden ingevoegd), kunnen nieuwe verklaringen worden toegevoegd zoals vereist zonder de actielabels te hernummeren of opnieuw te controleren en ervoor te zorgen dat de acties in de verwachte volgorde blijven worden uitgevoerd.

Er zijn veel voorkomende opdrachten die u aan het begin van uw EEM-scripts moet uitvoeren. Dit kan het volgende omvatten:

• Terminallengte instellen op 0
• Activeringsmodus inschakelen
• Automatische tijdstempel inschakelen voor opdrachtuitvoer

Dit is een veel voorkomend patroon in de voorbeelden die in dit document worden weergegeven, waarbij veel van de scripts beginnen met dezelfde 3 actie-instructies om dit te configureren.

Gemeenschappelijke logische EEM-patronen

Deze sectie behandelt een aantal gemeenschappelijke logica patronen en syntaxis blokken gebruikt in EEM scripts. De voorbeelden hier zijn geen complete scripts, maar eerder demonstraties van hoe specifieke functionaliteit kan worden gebruikt om complexe EEM-scripts te maken.

Codepaden voor vertakkingen met If/Else

EEM-variabelen kunnen worden gebruikt om de uitvoeringsstroom van EEM-scripts te regelen. Beschouw dit EEM script:

event manager applet snmp_cpu authorization bypass
event timer watchdog time 60
action 0010 info type snmp oid 1.3.6.1.4.1.9.9.109.1.1.1.1.3 get-type exact
action 0020 if $_info_snmp_value ge "50"
action 0030 syslog msg "This syslog message is sent if CPU utilization is above 50%"
action 0040 elseif $_info_snmp_value ge "30"
action 0050 syslog msg "This syslog message is sent if CPU utilization is above 30% and below 50%"
action 0060 else
action 0070 syslog msg "This syslog message is sent if CPU utilization is below 30%"
action 0080 end

Dit script draait elke minuut. Controleer de waarde van de SNMP OID voor CPU-gebruik en voer vervolgens een van de drie verschillende uitvoeringspaden in op basis van de waarde van de OID. Vergelijkbare statements kunnen worden gebruikt op elke andere juridische EEM variabele om complexe executiestromen in EEM scripts te bouwen.

Loop-over-instructies

Execution loops kunnen worden gebruikt om EEM-scripts aanzienlijk te verkorten en ze gemakkelijker te redeneren. Overweeg dit script, ontworpen om de interfacestatistieken voor Te2/1/15 6 keer over een periode van 1 minuut te trekken om te controleren op kleine periodes van hoog gebruik:

event manager applet int_util_check auth bypass
event timer watchdog time 300 maxrun 120
action 0001 cli command "enable"
action 0002 cli command "term exec prompt timestamp"
action 0003 cli command "term length 0"
action 0010 syslog msg "Running iteration 1 of command"
action 0020 cli command "show interface te2/1/15 | append flash:interface_util.txt"
action 0030 wait 10
action 0040 syslog msg "Running iteration 2 of command"
action 0050 cli command "show interface te2/1/15 | append flash:interface_util.txt"
action 0060 wait 10
action 0070 syslog msg "Running iteration 3 of command"
action 0080 cli command "show interface te2/1/15 | append flash:interface_util.txt"
action 0090 wait 10
action 0100 syslog msg "Running iteration 4 of command"
action 0110 cli command "show interface te2/1/15 | append flash:interface_util.txt"
action 0120 wait 10
action 0130 syslog msg "Running iteration 5 of command"
action 0140 cli command "show interface te2/1/15 | append flash:interface_util.txt"
action 0150 wait 10
action 0160 syslog msg "Running iteration 6 of command"
action 0170 cli command "show interface te2/1/15 | append flash:interface_util.txt"

Met EEM-lusconstructies kan dit script aanzienlijk worden ingekort:

event manager applet int_util_check auth bypass
event timer watchdog time 300 maxrun 120
action 0001 cli command "enable"
action 0002 cli command "term exec prompt timestamp"
action 0003 cli command "term length 0"
action 0010 set loop_iteration 1
action 0020 while $loop_iteration le 6
action 0030 syslog msg "Running iteration $loop_iteration of command"
action 0040 cli command "show interface te2/1/15 | append flash:interface_util.txt"
action 0050 wait 10
action 0060 increment loop_iteration 1
action 0070 end

Uitvoer extraheren via reguliere expressies (Regex)

De instructie EEM regexp kan worden gebruikt om waarden uit opdrachtuitvoer te halen die in volgende opdrachten moeten worden gebruikt en om dynamische opdrachtcreatie binnen het EEM-script zelf mogelijk te maken. Raadpleeg dit codeblok voor een voorbeeld om de SNMP ENGINE PID te extraheren uit de uitvoer van de show proc cpu | i SNMP-engine en af te drukken naar een syslog-bericht. Deze geëxtraheerde waarde kan ook worden gebruikt in andere opdrachten waarvoor een PID moet worden uitgevoerd.

event manager applet check_pid auth bypass
event none
action 0010 cli command "show proc cpu | i SNMP ENGINE" 
action 0020 regexp "^[ ]*([0-9]+) .*" $_cli_result match match1 
action 0030 syslog msg "Found SNMP Engine PID $match1"

Nuttige EEM-scripts

Specifiek MAC-adres bijhouden voor MAC-adres Learn

In dit voorbeeld wordt het MAC-adres b4e9.b0d3.6a41 bijgehouden. Het script controleert elke 30 seconden om te zien of het opgegeven MAC-adres is geleerd in de ARP- of MAC-tabellen. Als de MAC wordt gezien, voert het script de volgende acties uit:

• voert een syslog-bericht uit (Dit is handig als u wilt bevestigen waar een MAC-adres wordt geleerd of wanneer/hoe vaak het wordt geleerd). 

uitvoering

event manager applet mac_trace authorization bypass 
event timer watchdog time 30
action 0001 cli command "enable"
action 0002 cli command "term exec prompt timestamp"
action 0003 cli command "term length 0"
action 0010 cli command "show ip arp | in b4e9.b0d3.6a41"
action 0020 regexp ".*(ARPA).*" $_cli_result
action 0030 if $_regexp_result eq 1
action 0040 syslog msg $_cli_result
action 0050 end
action 0060 cli command "show mac add vlan 1 | in b4e9.b0d3.6a41"
action 0070 regexp ".*(DYNAMIC).*" $_cli_result
action 0080 if $_regexp_result eq 1
action 0090 syslog msg $_cli_result
action 0100 end

Hoge CPU bewaken via SNMP OID

Dit script bewaakt een SNMP OID die wordt gebruikt om het CPU-bezettingspercentage in de laatste 5 seconden te lezen. Wanneer de CPU meer dan 80% bezet is, voert het script de volgende acties uit:

• Hiermee maakt u een tijdstempel op basis van de uitvoer van de weergaveklok en gebruikt u deze om een unieke bestandsnaam te maken.
• Uitgangen over proces- en softwarestatus worden vervolgens naar dit bestand geschreven.
• Een Embedded Packet Capture (EPC) is geconfigureerd om 10 seconden verkeer vast te leggen dat bestemd is voor het controlevlak en schrijft het naar een bestand.
• Nadat de EPC-vastlegging is voltooid, wordt de EPC-configuratie verwijderd en wordt het script afgesloten.

uitvoering

event manager applet high-cpu authorization bypass
event snmp oid 1.3.6.1.4.1.9.9.109.1.1.1.1.3 get-type next entry-op gt entry-val 80 poll-interval 1 ratelimit 300 maxrun 180
action 0001 cli command "enable"
action 0002 cli command "term exec prompt timestamp"
action 0003 cli command "term length 0"
action 0010 syslog msg "High CPU detected, gathering system information."
action 0020 cli command "show clock"
action 0030 regex "([0-9]|[0-9][0-9]):([0-9]|[0-9][0-9]):([0-9]|[0-9][0-9])" $_cli_result match match1
action 0040 string replace "$match" 2 2 "."
action 0050 string replace "$_string_result" 5 5 "."
action 0060 set time $_string_result
action 0070 cli command "show proc cpu sort | append flash:tac-cpu-$time.txt"
action 0080 cli command "show proc cpu hist | append flash:tac-cpu-$time.txt"
action 0090 cli command "show proc cpu platform sorted | append flash:tac-cpu-$time.txt"
action 0100 cli command "show interface | append flash:tac-cpu-$time.txt"
action 0110 cli command "show interface stats | append flash:tac-cpu-$time.txt"
action 0120 cli command "show log | append flash:tac-cpu-$time.txt"
action 0130 cli command "show ip traffic | append flash:tac-cpu-$time.txt"
action 0140 cli command "show users | append flash:tac-cpu-$time.txt"
action 0150 cli command "show platform software fed switch active punt cause summary | append flash:tac-cpu-$time.txt"
action 0160 cli command "show platform software fed switch active cpu-interface | append flash:tac-cpu-$time.txt"
action 0170 cli command "show platform software fed switch active punt cpuq all | append flash:tac-cpu-$time.txt"
action 0180 cli command "no monitor capture tac_cpu"
action 0190 cli command "monitor capture tac_cpu control-plane in match any file location flash:tac-cpu-$time.pcap"
action 0200 cli command "monitor capture tac_cpu start" pattern "yes"
action 0210 cli command "yes"
action 0220 wait 10
action 0230 cli command "monitor capture tac_cpu stop"
action 0240 cli command "no monitor capture tac_cpu"   

Dynamisch matchen van een PID en Record Stack Output

Dit script zoekt naar een syslog-bericht dat de SNMP-invoerwachtrij vol is en onderneemt de volgende acties:

• Registreert de uitvoer van show proc cpu sorteren naar een bestand.
• Extracteert de PID van het SNMP ENGINE-proces via regex.
• Gebruikt de SNMP PID in volgende opdrachten om de stapelgegevens voor de PID te verkrijgen.
• Verwijdert het script uit de configuratie zodat er geen executies meer van plaatsvinden.

uitvoering

event manager applet TAC-SNMP-INPUT-QUEUE-FULL authorization bypass
event syslog pattern "INPUT_QFULL_ERR" ratelimit 40 maxrun 120
action 0010 cli command "en"
action 0020 cli command "show proc cpu sort | append flash:TAC-SNMP.txt"
action 0030 cli command "show proc cpu | i SNMP ENGINE"
action 0040 regexp "^[ ]*([0-9]+) .*" $_cli_result match match1
action 0050 syslog msg "Found SNMP Engine PID $match1"
action 0060 cli command "show stacks $match1 | append flash:TAC-SNMP.txt"
action 0070 syslog msg "$_cli_result"
action 0080 cli command "configure terminal"
action 0090 cli command "no event manager applet TAC-SNMP-INPUT-QUEUE-FULL"
action 0100 cli command "end"

Upgrade een Switch

Dit script is zo geconfigureerd dat de patroonovereenkomst wordt weergegeven op de niet-standaardprompt die wordt geretourneerd door de opdracht install add file <file> activate commit en reageert op de prompts. Er is geen triggergebeurtenis geconfigureerd, dus het EEM-script moet handmatig door een gebruiker worden geactiveerd wanneer de upgrade via gebeurtenisbeheer moet worden uitgevoerd UPGRADE. De maxrun-timer is ingesteld op 300 seconden in plaats van de standaardwaarde van 20 seconden, omdat het uitvoeren van de opdracht toevoegen van installatie veel tijd in beslag neemt.

uitvoering

event manager applet UPGRADE authorization bypass
event none maxrun 300
action 0001 cli command "enable"
action 0002 cli command "term length 0"
action 0020 cli command "install add file flash:cat9k_iosxe.16.06.02.SPA.bin activate commit" pattern "y\/n"
action 0030 cli command "y" pattern "y\/n"
action 0040 syslog msg  "Reloading device to upgrade code"
action 0050 cli command "y"

Diagnostische gegevens naar een bestand dumpen wanneer een IP SLA-trackingobject wordt afgebroken

Dit script wordt geactiveerd wanneer IP SLA-object 11 wordt uitgeschakeld en de volgende acties uitvoert:

• Verzamel MAC-tabel, ARP-tabel, syslogs en routeringstabel.
• Schrijf informatie naar een bestand op flash: genaamd sla_track.txt.

uitvoering

ip sla 10
icmp-echo 10.10.10.10 source-ip 10.10.10.10
frequency 10
exit
ip sla schedule 10 life forever start-time now
track 11 ip sla 10 reachability
exit
event manager applet track-10 authorization bypass 
event track 11 state down
action 0001 cli command "enable"
action 0002 cli command "term exec prompt timestamp"
action 0003 cli command "term length 0"
action 0010 syslog msg  "IP SLA object 10 has gone down"
action 0020 cli command "show mac address-table detail | append flash:sla_track.txt"
action 0030 cli command "show ip arp | append flash:sla_track.txt"
action 0040 cli command "show log | append flash:sla_track.txt"
action 0050 cli command "show ip route | append flash:sla_track.txt"

Stuur een e-mail van EEM

Dit script wordt geactiveerd wanneer het patroon beschreven in de gebeurtenis syslog patroon instructie wordt gezien, en neemt de volgende acties:

• Verstuurt een e-mail vanaf een interne e-mailserver (hierbij wordt ervan uitgegaan dat de interne e-mailserver open verificatie vanaf het apparaat mogelijk maakt).

uitvoering

event manager environment email_from email_address@company.test
event manager environment email_server 192.168.1.1
event manager environment email_to dest_address@company.test
event manager applet email_syslog
event syslog pattern "SYSLOG PATTERN HERE” maxrun 60
action 0010 info type routername
action 0020 mail server "$email_server" to "$email_to" from "$email_from" subject "SUBJECT OF EMAIL - Syslog seen on $_info_routername" body “BODY OF YOUR EMAIL GOES HERE”

Een poort op een schema afsluiten

Dit script sluit elke dag om 18.00 uur poort Te2/1/15 af.

uitvoering

event manager applet shut_port authorization bypass 
event timer cron cron-entry "0 18 * * *"
action 0001 cli command "enable"
action 0002 cli command "term exec prompt timestamp"
action 0003 cli command "term length 0"
action 0010 syslog msg  "shutting port Te2/1/15 down"
action 0030 cli command "config t"
action 0040 cli command "int Te2/1/15"
action 0050 cli command "shutdown"
action 0060 cli command "end"

Sluit een interface af als de snelheid van een gegeven pakket per seconde (PPS) wordt bereikt

Dit script controleert de PPS-snelheid op interface Te2/1/9 in de TX-richting elke seconde. Als het PPS-percentage hoger is dan 100, onderneemt het de volgende acties:

• Registreert de uitvoer show int  voor de interface naar syslog.
• Schakelt de interface uit.

uitvoering

event manager applet disable_link authorization bypass 
event interface name te2/1/9  parameter  transmit_rate_pps entry-op ge entry-val 100 poll-interval 1 entry-type value
action 0001 cli command "enable"
action 0002 cli command "term length 0"
action 0010 syslog msg  "Detecting high input rate on interface te2/1/9.  Shutting interface down."
action 0020 cli command "show int te2/1/9"
action 0030 syslog msg  $_cli_result
action 0040 cli command "config t"
action 0050 cli command "int te2/1/9"
action 0060 cli command "shutdown"
action 0070 cli command "end"

Gerelateerde informatie

• Best practices voor Cisco EEM
• Cisco Technical Support en downloads