Libreria gestione SNMP (eLLabSNMPLib) ------------------------------------- **Attenzione! Per utilizzare la libreria occorre importarla nel proprio progetto**. Vedere capitolo relativo all'\ `import delle librerie <#7.2.1.Import libreria|outline>`__. Il Simple network management protocol (spesso abbreviato in Snmp) è un dei protocolli di Rete appartenenti alla suite TCP/IP e operante al livello 7 del modello ISO/OSI. Lo SNMP consente la configurazione, la gestione e la supervisione di dispositivi di rete collegati a una LAN o a una rete geografica più estesa. Solitamente, il protocollo è supportato da dispositivi quali router, switch di rete, server, stampanti di rete e altri. Il Simple network management protocol permette agli amministratori di rete e ai sistemisti di tenere sotto controllo le performance della rete, risolvere eventuali problematiche e pianificare uno sviluppo futuro della rete. Questa libreria pubblica oggetti per gestire il protocollo sia lato Server (Agent) che lato Client (Manager). **Agent:** Permette l’accesso all’informazione da gestire da parte delle applicazioni esterne permette la modifica dei parametri di funzionamento e fornisce funzioni di polling, misura, monitoraggio, statistiche. **Manager:** Anche chiamato Management Station agisce come punto di raccolta e di elaborazione delle informazioni ricavate dai vari Agent degli apparati. PDUType, definizione tipo query SNMP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Le query supportate dal gestore SNMP manager sono riportate nella tabella seguente. +-----------------------+-----------------------+-----------------------+ | **PDUType** | **Function** | **Description** | +-----------------------+-----------------------+-----------------------+ | 16#A0 | GetRequest | This PDU is sent from | | | | a management station | | | | to the agent and is | | | | used to retrieve the | | | | values of object | | | | instances whose OIDs | | | | are contained in the | | | | PDU. | +-----------------------+-----------------------+-----------------------+ | 16#A1 | GetNextRequest | This PDU is sent from | | | | a management station | | | | to the agent and is | | | | used to retrieve the | | | | values of the object | | | | instances whose OIDs | | | | are lexicographically | | | | next to that of the | | | | OID contained in the | | | | PDU. | +-----------------------+-----------------------+-----------------------+ | 16#A3 | SetRequest | This PDU is sent from | | | | a management station | | | | to the agent and is | | | | used to set the | | | | values of object | | | | instances whose OIDs | | | | and value are | | | | contained in the PDU. | +-----------------------+-----------------------+-----------------------+ VType, definizione tipo variabile ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Il gestore SNMP manager opera solo su alcuni tipi di variabili in funzione del **Data Type** gestito nel frame SNMP. +-----------------------+-----------------------+-----------------------+ | **VType** | **Value** | **Description** | +-----------------------+-----------------------+-----------------------+ | SNMP_VT_INTEGER | 16#02 | **Integer:** Must | | | | refer to a signed | | | | 32bit Integer DINT | | | | variable. | | | | | | | | (Values between | | | | -2147483648 and | | | | 2147483647). | +-----------------------+-----------------------+-----------------------+ | SNMP_VT_STRING | 16#04 | **Octect string:** | | | | Must refer to a | | | | STRING variable. | | | | | | | | Arbitrary binary or | | | | textual data, | | | | typically limited to | | | | 255 characters in | | | | length. | +-----------------------+-----------------------+-----------------------+ | SNMP_VT_NULL | 16#05 | **Null:** Must refer | | | | to a Null pointer. | +-----------------------+-----------------------+-----------------------+ | SNMP_VT_IPADDRESS | 16#40 | **IPAddress:** Must | | | | refer to a STRING | | | | variable. | | | | | | | | An IP address in | | | | textual data, limited | | | | to 15 characters | | | | length. | +-----------------------+-----------------------+-----------------------+ | SNMP_VT_COUNTER32 | 16#41 | **Counter32:** Must | | | | refer to a unsigned | | | | 32bit Integer UDINT | | | | variable. | | | | | | | | Represents a | | | | non-negative integer | | | | which monotonically | | | | increases until it | | | | reaches a maximum | | | | value of 32bits-1 | | | | (4294967295 dec), | | | | when it wraps around | | | | and starts increasing | | | | again from zero. | +-----------------------+-----------------------+-----------------------+ | SNMP_VT_GAUGE32 | 16#42 | **Gauge32:** Must | | | | refer to a unsigned | | | | 32bit Integer UDINT | | | | variable. | | | | | | | | Represents a | | | | non-negative integer, | | | | which holds at the | | | | maximum or minimum | | | | value specified in | | | | the range when the | | | | actual value goes | | | | over or below the | | | | range, respectively. | +-----------------------+-----------------------+-----------------------+ | SNMP_VT_TIMETICKS | 16#43 | **TimeTicks:** Must | | | | refer to a unsigned | | | | 32bit Integer UDINT | | | | variable. | | | | | | | | Represents an | | | | unsigned integer | | | | which represents the | | | | time, in hundredths | | | | of a second between | | | | two epochs. | +-----------------------+-----------------------+-----------------------+ ECode, definizione codice errore ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Viene ritornato il codice di errore ricevuto da Agent. +-----------------------+-----------------------+-----------------------+ | **ECode** | **Error** | **Descritption** | +-----------------------+-----------------------+-----------------------+ | 0 | noError | No error occurred. | | | | This code is also | | | | used in all request | | | | PDUs, since they have | | | | no error status to | | | | report. | +-----------------------+-----------------------+-----------------------+ | 1 | tooBig | The size of the | | | | Response-PDU would be | | | | too large to | | | | transport. | +-----------------------+-----------------------+-----------------------+ | 2 | noSuchName | The name of a | | | | requested object was | | | | not found. | +-----------------------+-----------------------+-----------------------+ | 3 | badValue | A value in the | | | | request didn't match | | | | the structure that | | | | the recipient of the | | | | request had for the | | | | object. For example, | | | | an object in the | | | | request was specified | | | | with an incorrect | | | | length or type. | +-----------------------+-----------------------+-----------------------+ | 4 | readOnly | An attempt was made | | | | to set a variable | | | | that has an Access | | | | value indicating that | | | | it is read-only. | +-----------------------+-----------------------+-----------------------+ | 5 | genErr | An error occurred | | | | other than one | | | | indicated by a more | | | | specific error code | | | | in this table. | +-----------------------+-----------------------+-----------------------+ | 6 | noAccess | Access was denied to | | | | the object for | | | | security reasons. | +-----------------------+-----------------------+-----------------------+ | 7 | wrongType | The object type in a | | | | variable binding is | | | | incorrect for the | | | | object. | +-----------------------+-----------------------+-----------------------+ | 8 | wrongLength | A variable binding | | | | specifies a length | | | | incorrect for the | | | | object. | +-----------------------+-----------------------+-----------------------+ | 9 | wrongEncoding | A variable binding | | | | specifies an encoding | | | | incorrect for the | | | | object. | +-----------------------+-----------------------+-----------------------+ | 10 | wrongValue | The value given in a | | | | variable binding is | | | | not possible for the | | | | object. | +-----------------------+-----------------------+-----------------------+ | 11 | noCreation | A specified variable | | | | does not exist and | | | | cannot be created. | +-----------------------+-----------------------+-----------------------+ | 12 | inconsistentValue | A variable binding | | | | specifies a value | | | | that could be held by | | | | the variable but | | | | cannot be assigned to | | | | it at this time. | +-----------------------+-----------------------+-----------------------+ | 13 | resourceUnavailable | An attempt to set a | | | | variable required a | | | | resource that is not | | | | available. | +-----------------------+-----------------------+-----------------------+ | 14 | commitFailed | An attempt to set a | | | | particular variable | | | | failed. | +-----------------------+-----------------------+-----------------------+ | 15 | undoFailed | An attempt to set a | | | | particular variable | | | | as part of a group of | | | | variables failed, and | | | | the attempt to then | | | | undo the setting of | | | | other variables was | | | | not successful. | +-----------------------+-----------------------+-----------------------+ | 16 | authorizationError | A problem occurred in | | | | authorization. | +-----------------------+-----------------------+-----------------------+ | 17 | notWritable | The variable cannot | | | | be written or | | | | created. | +-----------------------+-----------------------+-----------------------+ | 18 | inconsistentName | The name in a | | | | variable binding | | | | specifies a variable | | | | that does not exist. | +-----------------------+-----------------------+-----------------------+ SNMPVARIABLEDEFS, definizione variabile SNMP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Questo tipo di dati è utilizzato dal blocco funzione **SNMPAgent** per la definizione degli oggetti gestiti. +-----------------------+-----------------------+-----------------------+ | **Name** | **Type** | **Description** | +-----------------------+-----------------------+-----------------------+ | Type | USINT | Tipo variabile (`Vedi | | | | tabella <#vtype-defin | | | | izione-tipo-variabile | | | | >`__). | +-----------------------+-----------------------+-----------------------+ | Writable | BOOL | Se TRUE la variabile | | | | può essere scritta. | +-----------------------+-----------------------+-----------------------+ | OID | @USINT | Indirizzo stringa | | | | definizione Object | | | | Identifier. | +-----------------------+-----------------------+-----------------------+ | Address | @USINT | Indirizzo allocazione | | | | variabile. | +-----------------------+-----------------------+-----------------------+ | Length | UDINT | Lunghezza variabile. | +-----------------------+-----------------------+-----------------------+ SNMPAgent, manages the SNMP Agent ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------------------+ | **Type** | **Library** | +----------+-------------------+ | FB | eLLabSNMPLib_A000 | +----------+-------------------+ |image0| Questo blocco funzione esegue la gestione del protocollo SNMP agendo come Agent. Attivando l'FB si pone in ascolto l'agente sulla porta definita, sono accettate il numero di connessioni contemporanee definite in **Connections**. In **Community** occorre definire l'indirizzo della stringa di definizione della comunità accettata dall'Agent. Per la definizione delle variabili gestite dall'Agent è definita nella libreria una apposita struttura dati. La struttura `SNMPVARIABLEDEFS <#TabSNMPVARIABLEDEFS>`__ permette di definire le variabili su cui l'Agent può operare. In **VDefs** occorre fornire l'indirizzo di allocazione della struttura di definizione variabili ed in **VNr** occorre definire il numero delle variabili definite. Il FB gestisce autonomamente il comando SnmpWalk permettendo di “camminare” tra tutte le variabili definite. +-----------------------------------+-----------------------------------+ | **Enable** (BOOL) | Comando attivazione SNMP Agent. | +-----------------------------------+-----------------------------------+ | **SpyOn** (BOOL) | Se attivo permette di spiare il | | | funzionamento della FB. | +-----------------------------------+-----------------------------------+ | **Port** (UINT) | Porta UDP su cui porre in ascolto | | | l'Agent. Solitamente si utilizza | | | la porta 161. | +-----------------------------------+-----------------------------------+ | **Connections** (USINT) | Numero di connessioni | | | contemporanee gestite dal FB (Da | | | 1 a 4). | +-----------------------------------+-----------------------------------+ | **Community** (@USINT) | Indirizzo allocazione stringa | | | definizione Community. | +-----------------------------------+-----------------------------------+ | **VDefs** (@SNMPVARIABLEDEFS) | Indirizzo allocazione struttura | | | **SNMPVARIABLEDEFS**. | +-----------------------------------+-----------------------------------+ | **VNr** (USINT) | Numero di variabili definite. | +-----------------------------------+-----------------------------------+ | **Timeout** (UINT) | Timeout esecuzione query SNMP | | | (mS). | +-----------------------------------+-----------------------------------+ | **Enabled** (BOOL) | Blocco funzione abilitato. | +-----------------------------------+-----------------------------------+ | **Fault** (BOOL) | Attivo per un loop di programma | | | se errore gestione. | +-----------------------------------+-----------------------------------+ **Codici di errore** In caso di errore si attiva l'uscita **Fault**, con `SysGetLastError <#FctSysGetLastError>`__ è possibile rilevare il codice di errore. +-------------+---------------------------------------------------------------+ | **Codice** | **Descrizione** | +-------------+---------------------------------------------------------------+ | 10059020 | FB eseguita in una task diversa dalla task di background. | +-------------+---------------------------------------------------------------+ | 10059030 | Connections non impostato correttamente. | +-------------+---------------------------------------------------------------+ | 10059080 | Timeout esecuzione. | +-------------+---------------------------------------------------------------+ | 10059090 | Errore interno. | +-------------+---------------------------------------------------------------+ | 10059100~2 | Errore ricezione intestazione frame SNMP da Manager. | +-------------+---------------------------------------------------------------+ | 10059110 | PDU type ricevuto non gestito. | +-------------+---------------------------------------------------------------+ | 10059200~99 | Errore nella decodifica del comando SNMP ricevuto da Manager. | +-------------+---------------------------------------------------------------+ | 10059300~99 | Errore nella codifica della risposta SNMP verso Manager. | +-------------+---------------------------------------------------------------+ **Esempi** """""""""""" Nell'esempio viene gestito un agente SNMP, l'agente opera su due variabili. **Definizione variabili** |image1| **Esempio ST** *(PTP137A000, ST_SNMPAgent)* .. code-block:: none (\* Program initialization \*) IF (SysFirstLoop) THEN (\* Parametrize the SNMP Agent FB. \*) SNMPAgt.SpyOn:=TRUE; (\* Spy command \*) SNMPAgt.Port:=161; (\* Agent port \*) SNMPAgt.Connections:=2; (\* Accepted connections \*) SNMPAgt.Community:=ADR('public'); (\* Community \*) SNMPAgt.VDefs:=ADR(VDefs); (\* Variable definitions \*) SNMPAgt.VNr:=2; (\* Variable number \*) SNMPAgt.Timeout:=1000; (\* Timeout (mS) \*) (\* Definition of the variables on wich the Agent can operate. \*) VDefs[0].Type:=16#02; (\* Variable type \*) VDefs[0].Writable:=TRUE; (\* Variable can be written \*) VDefs[0].OID:=ADR('1.3.6.1.4.1.36955.1'); (\* OID definition \*) VDefs[0].Address:=ADR(Value); (\* Variable address \*) VDefs[0].Length:=SIZEOF(Value); (\* Variable length \*) VDefs[1].Type:=16#04; (\* Variable type \*) VDefs[1].Writable:=FALSE; (\* Variable cannot be written \*) VDefs[1].OID:=ADR('1.3.6.1.4.1.36955.2'); (\* OID definition \*) VDefs[1].Address:=ADR('Hello!'); (\* Variable address \*) VDefs[1].Length:=Sysstrlen(VDefs[1].Address); (\* Variable length \*) END_IF; (\* Manage the SNMP Agent. \*) SNMPAgt(Enable:=TRUE); (\* SNMP Agent \*) (\* [End of file] \*) Ecco il risultato di un comando SnmpWalk inviato all'Agent: .. code-block:: none SnmpWalk -r:192.168.0.181 SnmpWalk v1.01 - Copyright (C) 2009 SnmpSoft Company OID=.1.3.6.1.4.1.36955.1, Type=Integer, Value=-1350 OID=.1.3.6.1.4.1.36955.2, Type=OctetString, Value=Hello! Total: 2 _section-1: SNMPManager, sends a SNMP message ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------+-------------------+ | **Type** | **Library** | +----------+-------------------+ | FB | eLLabSNMPLib_A000 | +----------+-------------------+ |image2| Questo blocco funzione esegue la gestione del protocollo SNMP agendo come Manager. Attivando l'FB viene inviato un pacchetto SNMP con il valore di **PDUType** indicato. Eseguito l'invio e ricevuta la richiesta dall'Agent viene attivata l'uscita **Done**. Per inviare un nuovo pacchetto occorre disabilitare e poi riabilitare **Enable**. Attivando **Enable** viene inviato all'Agent con indirizzo **Address** sulla porta **Port** il messaggio SNMP di tipo **PDUType** con **OID** definito. Se il messaggio è di tipo lettura, al termine, nella variabile indicata sarà trasferito il valore della variabile acquisita dall'Agent. Se il messaggio è di tipo scrittura, al termine il valorte della variabile definita sarà stato trasferito nell'Agent. In **Community** occorre definire l'indirizzo della stringa di definizione della comunità accettata dall'Agent. +-----------------------------------+-----------------------------------+ | **Enable** (BOOL) | Comando attivazione SNMP Manager. | +-----------------------------------+-----------------------------------+ | **SpyOn** (BOOL) | Se attivo permette di spiare il | | | funzionamento della FB. | +-----------------------------------+-----------------------------------+ | **Address** (@USINT) | Indirizzo IP o URL dell'Agent a | | | cui inviare la query SNMP. | +-----------------------------------+-----------------------------------+ | **Port** (UINT) | Porta UDP a cui inviare la query. | | | Solitamente si utilizza la porta | | | 161. | +-----------------------------------+-----------------------------------+ | **Community** (@USINT) | Indirizzo allocazione stringa | | | definizione Community. | +-----------------------------------+-----------------------------------+ | **PDUType** (USINT) | Tipo di query SNMP da inviare | | | (`Vedi | | | tabella <#pdutype-definizione-tip | | | o-query-snmp>`__). | +-----------------------------------+-----------------------------------+ | **OID** (@USINT) | Indirizzo stringa definizione | | | Object Identifier da richiedere. | +-----------------------------------+-----------------------------------+ | **VType** (USINT) | Tipo variabile ricevuta/da | | | inviare (`Vedi | | | tabella <#vtype-definizione-tipo- | | | variabile>`__). | +-----------------------------------+-----------------------------------+ | **VAddress** (@USINT) | Indirizzo allocazione variabile | | | ricevuta/da inviare. | +-----------------------------------+-----------------------------------+ | **VLength** (UDINT) | Lunghezza variabile ricevuta/da | | | inviare. | +-----------------------------------+-----------------------------------+ | **Timeout** (UINT) | Timeout esecuzione query SNMP | | | (mS). | +-----------------------------------+-----------------------------------+ | **Done** (BOOL) | Esecuzione comando terminata. | +-----------------------------------+-----------------------------------+ | **Ok** (BOOL) | Attivo per un loop di programma | | | se comando eseguito | | | correttamente. | +-----------------------------------+-----------------------------------+ | **Fault** (BOOL) | Attivo per un loop di programma | | | se errore gestione. | +-----------------------------------+-----------------------------------+ | **ECode** (USINT) | Riporta l'eventuale codice di | | | errore ricevuto dall'Agent (`Vedi | | | tabella <#TabSNMPECode>`__). | +-----------------------------------+-----------------------------------+ | **EIndex** (USINT) | Riporta l'eventuale indice di | | | errore ricevuto dall'Agent. | +-----------------------------------+-----------------------------------+ **Codici di errore** In caso di errore si attiva l'uscita **Fault**, con `SysGetLastError <#FctSysGetLastError>`__ è possibile rilevare il codice di errore. +-----------------------------------+-----------------------------------+ | **Codice** | **Descrizione** | +-----------------------------------+-----------------------------------+ | 10060020 | FB eseguita in una task diversa | | | dalla task di background. | +-----------------------------------+-----------------------------------+ | 10060080 | Timeout esecuzione. | +-----------------------------------+-----------------------------------+ | 10060090 | Errore interno. | +-----------------------------------+-----------------------------------+ | 10060100~99 | Errore nella codifica del comando | | | SNMP verso Agent. | +-----------------------------------+-----------------------------------+ | 10060200~2 | Errore ricezione intestazione | | | frame risposta SNMP da Agent. | +-----------------------------------+-----------------------------------+ | 10060300~99 | Errore nella decodifica della | | | risposta SNMP ricevuta da Agent. | +-----------------------------------+-----------------------------------+ | 10060400~9 | Errore dati nella risposta SNMP | | | ricevuta da Agent. | +-----------------------------------+-----------------------------------+ | 10060410~9 | Errore impostazione **VType**. | +-----------------------------------+-----------------------------------+ | 10060420~9 | Errore impostazione **VLength**. | +-----------------------------------+-----------------------------------+ **Esempi** """""""""""""" Nell'esempio viene eseguita una richiesta SNMP verso un Agent su un altro sistema SlimLine. Attivando **Di00CPU** viene richiesto l'OID 1.3.6.1.4.1.36955.2 su di un sistema SlimLine dove è in esecuzione il programma Agent. L'agente risponderà inviando una variabile stringa con contenuto “Hello!”. **Definizione variabili** |image4| **Esempio ST** *(PTP137A000, ST_SNMPManager)* .. code-block:: none (\* Program initialization \*) IF (SysFirstLoop) THEN SNMPMng.Port:=161; (\* Peer port \*) SNMPMng.SpyOn:=TRUE; (\* Spy command \*) SNMPMng.PDUType:=16#A0; (\* PDU type \*) SNMPMng.Community:=ADR('public'); (\* Community \*) SNMPMng.Timeout:=1000; (\* Execution timeout (mS) \*) SNMPMng.VType:=16#04; (\* Variable type \*) SNMPMng.VLength:=SIZEOF(Str); (\* Variable length \*) SNMPMng.VAddress:=ADR(Str); (\* Variable address \*) SNMPMng.Address:=ADR('192.168.0.184'); (\* Agent address \*) SNMPMng.OID:=ADR('1.3.6.1.4.1.36955.2'); (\* OID \*) END_IF; (\* SNMP manager. \*) SNMPMng.Enable:=Di00CPU; SNMPMng(); (\* SNMP manager \*) (\* Check if the answer from Agent has been received and manage it. \*) IF (SNMPMng.Ok) THEN Ok:=TO_BOOL(SysStrFind(ADR(Str), ADR('Hello!'), FIND_DEFAULT) = ADR(Str)); (\* [End of file] \*) .. |image0| image:: media/image1.jpg :width: 1.88611in :height: 1.87431in .. |image1| image:: media/image2.jpg :width: 7.08681in :height: 0.73611in .. |image2| image:: media/image3.jpg :width: 1.70833in :height: 2.45694in .. |image3| image:: media/image4.jpg :width: 7.08681in :height: 0.61042in .. |image4| image:: media/image4.jpg :width: 7.08681in :height: 0.61042in