# SNMP

> Gli apparati di rete che rispondono in SNMP v1, v2c o v3 (gruppi di continuità, PDU, switch, router, condizionamento di precisione e sensori ambientali) letti tramite il loro agente all'intervallo di interrogazione di ogni tag: la scheda Agente SNMP, l'OID di un tag in numeri o con il nome standard, i tipi di dato in cui si legge ogni oggetto, lettura e scrittura, il percorso che rileva gli oggetti di un agente e due esempi completi.

Il driver **SNMP** legge e scrive gli apparati di una sala tecnica tramite il loro agente SNMP: gruppi
di continuità, PDU, switch, router, condizionamento di precisione e sensori di temperatura o umidità.
Completa il driver [Redfish](driver-redfish), che legge i controller di gestione dei server: insieme
coprono la sala tecnica. Ogni tag legge un oggetto dell'agente tramite il suo OID, come
`upsBatteryStatus.0` o `ifHCInOctets.2`, e i suoi valori arrivano dove arrivano quelli di ogni altro
tag: in Logic, sulle dashboard, nelle prove di un banco di collaudo di [Process](process).

È la stazione a chiedere: ogni tag viene letto al suo intervallo di interrogazione, in SNMPv1, SNMPv2c o
SNMPv3, e l'**Intervallo di interrogazione (ms)** della scheda Dispositivo funziona come in ogni driver,
e ogni tag può sostituirlo. Quello che l'apparato manda da sé, le sue trap, non viene ricevuto; vedi
[Limiti da conoscere](#limits-worth-knowing).

Un dispositivo di questo driver è un agente, raggiunto sul suo host alla porta UDP 161. I dispositivi
stanno sotto il driver e possono essere archiviati in cartelle,
**Driver → Cartella → Dispositivo → Tag**, come sotto ogni driver senza linea seriale né broker.

## La pagina del driver {#the-drivers-page}

Per Configurare il connector, la pagina porta la scheda Ambito della scansione propria del driver, con
l'agente e i sottoalberi che Rileva percorre (vedi [Rilevamento](#discovery)). Sotto si trova la
tabella **Dispositivi** di ogni driver (vedi
[La tabella dei dispositivi](connector-drivers#the-device-table)), che cresce con
**Aggiungi dispositivo**, a destra del suo titolo; vuota, dice « Nessun dispositivo. » La barra del
driver porta **Rileva**, in grigio finché la scheda Ambito della scansione non è completa.

## Dispositivo {#device}

### Connessione {#connection}

| Campo | Significato | Predefinito |
| --- | --- | --- |
| **Indirizzo host** | Il nome host o l'indirizzo IP dell'agente. | vuoto |
| **Porta** | La porta UDP su cui l'agente risponde, da 1 a 65535. Una casella vuota mostra 161 in grigio e l'agente viene interrogato su di essa. | 161 |

Un dispositivo nuovo non ha host: dice « Indirizzo host non ancora inserito », e non viene inviato
nulla finché non ne ha uno. La Base URI che l'intestazione mostra è l'indirizzo di runtime, con la
versione, la sicurezza SNMPv3 in vigore, il timeout di risposta e i tentativi aggiuntivi:
`snmp://192.168.10.40:161?version=2c&timeoutMs=2000&retries=1`, oppure
`snmp://192.168.10.2:161?version=3&security=authPriv&auth=sha256&priv=aes128&timeoutMs=2000&retries=1`.
Non porta mai la community, l'utente né una password.

### La scheda Agente SNMP {#the-snmp-agent-card}

Sotto la scheda Connessione, la scheda **Agente SNMP** dice come viene interrogato l'agente. I campi che
disegna seguono la versione e, in SNMPv3, il livello di sicurezza.

| Campo | Mostrato | Significato | Predefinito |
| --- | --- | --- | --- |
| **Versione SNMP** | sempre | SNMPv1, SNMPv2c o SNMPv3, ognuna con una riga sotto. SNMPv1: « SNMPv1 non ha contatori a 64 bit, e un oggetto che manca all'agente fa rifiutare l'intera richiesta, che il driver ripete allora senza di esso. » SNMPv2c: « SNMPv2c legge i contatori a 64 bit, e un oggetto che manca all'agente fa fallire solo quel tag. Lo parlano quasi tutti gli apparati. » SNMPv3: « SNMPv3 si identifica con un utente, e firma e cifra i messaggi secondo il livello di sicurezza. » | SNMPv2c |
| **Community** | SNMPv1, SNMPv2c | La community a cui l'agente risponde, al massimo 255 byte, in una casella che nasconde ciò che si scrive; vuota, mostra `public` come suggerimento, mai come valore. Sotto: « Un agente ignora una richiesta con una community che non accetta, quindi una community sbagliata sembra un agente che non risponde. » | vuoto |
| **Utente SNMPv3** | SNMPv3 | L'utente che l'agente conserva, al massimo 32 caratteri. | vuoto |
| **Livello di sicurezza** | SNMPv3 | **Firmato e cifrato (authPriv)**: « Ogni messaggio è firmato con la password di autenticazione e cifrato con la password di cifratura. » **Solo firmato (authNoPriv)**: « Ogni messaggio è firmato con la password di autenticazione e viaggia in chiaro. » **Né firmato né cifrato (noAuthNoPriv)**: « Viene inviato solo il nome utente: niente è firmato e niente è cifrato. » | **Firmato e cifrato (authPriv)** |
| **Protocollo di autenticazione** | SNMPv3, firmato | MD5, SHA-1, SHA-256, SHA-384 o SHA-512. | SHA-1 |
| **Password di autenticazione** | SNMPv3, firmato | La password che firma i messaggi. | vuoto |
| **Protocollo di cifratura** | SNMPv3, authPriv | DES, AES-128, AES-192 o AES-256. | AES-128 |
| **Password di cifratura** | SNMPv3, authPriv | La password che cifra i messaggi. | vuoto |
| **Timeout di risposta (ms)** | sempre | Da 100 a 60000: « Quanto attende una richiesta la risposta dell'agente prima di essere inviata di nuovo. » | 2000 |
| **Tentativi aggiuntivi** | sempre | Da 0 a 5: « Quante volte una richiesta senza risposta viene inviata di nuovo prima che il dispositivo risulti offline. » | 1 |

Sotto le due password: « Ogni password è quella che l'agente conserva per questo utente, di almeno 8 caratteri. »
L'utente, il livello di sicurezza e i due protocolli sono quelli che l'agente ha configurato per
quell'utente, nella pagina delle impostazioni dell'apparato stesso: la stazione non può chiederli
all'agente. MD5, SHA-1 e DES sono offerti perché molti apparati installati non accettano nulla di più
recente.

Una credenziale non ancora inserita non è un errore: il dispositivo viene salvato, il driver non manda
nulla all'agente finché non c'è, e una riga pacata sotto la scheda dice cosa manca, la prima di queste:

| Manca | La scheda dice |
| --- | --- |
| La community (SNMPv1, SNMPv2c) | « Inserire la community a cui risponde l'agente. Fino ad allora il dispositivo non invia nulla. » |
| L'utente (SNMPv3) | « Inserire l'utente SNMPv3. Fino ad allora il dispositivo non invia nulla. » |
| La password di autenticazione (authNoPriv, authPriv) | « Inserire la password di autenticazione. Fino ad allora il dispositivo non invia nulla. » |
| La password di cifratura (authPriv) | « Inserire la password di cifratura. Fino ad allora il dispositivo non invia nulla. » |

Un dispositivo che ha il suo host e a cui manca ancora una credenziale non si connette, e il suo ultimo
errore nomina la credenziale che il suo agente aspetta. Un valore che la scheda non accetta non viene
salvato, e la scheda dice perché, in rosso:

| Scrivi | La scheda dice |
| --- | --- |
| Una password di autenticazione di meno di 8 caratteri | « La password di autenticazione deve avere almeno 8 caratteri. » |
| Una password di cifratura di meno di 8 caratteri | « La password di cifratura deve avere almeno 8 caratteri. » |
| Un utente di più di 32 caratteri, o una community di più di 255 byte | « L'utente ammette al massimo 32 caratteri e la community al massimo 255 byte. » |
| Un timeout di risposta fuori da 100 a 60000, o tentativi aggiuntivi fuori da 0 a 5 | La casella torna al valore in vigore e dice « Immettere un numero compreso tra 100 e 60000. » o « Immettere un numero compreso tra 0 e 5. » |

Il salvataggio applica le stesse regole della scheda, e il registro delle azioni lo dice quando ne
rifiuta una:
« Il dispositivo 'UPS room 1' ha un'impostazione SNMP che il suo driver non può usare. Aprirlo e correggere il campo che il pannello segnala. »
La community e le due password sono conservate come ogni credenziale di dispositivo (vedi
[Credenziali e certificati](connector-devices#credentials-and-certificates)): protette a riposo per
l'account Windows che le ha inserite, sigillate nell'esportazione della configurazione, e mai mostrate
nella Base URI, nel diario tecnico né nella risposta di un agente. Una credenziale inserita con un altro
account Windows torna vuota, e il dispositivo la aspetta come una mai inserita.

## Indirizzamento del tag {#tag-addressing}

### L'OID {#the-oid}

Un tag di questo driver legge un oggetto del suo agente. La scheda Sorgente del tag porta la casella
**OID**, con il suggerimento
« Un OID in numeri, ad esempio 1.3.6.1.2.1.1.3.0, oppure un nome standard con la sua istanza, ad esempio sysUpTime.0, ifInOctets.2 o upsBatteryStatus.0 »
sotto. Ogni richiesta porta il numero, qualunque sia la forma in cui il tag è scritto:

| Scritto | Letto come |
| --- | --- |
| `1.3.6.1.2.1.1.3.0`, `.1.3.6.1.2.1.1.3.0`, `iso.3.6.1.2.1.1.3.0` | Quel numero, che il pannello chiama `sysUpTime.0`. |
| `sysUpTime.0`, `sysUpTime`, `SNMPv2-MIB::sysUpTime.0`, senza badare a maiuscole e minuscole | Un valore singolo, la cui unica istanza `.0` si può omettere. |
| `ifInOctets.2` | Una colonna di una tabella con l'indice della sua riga, qui l'interfaccia 2, che si scrive sempre. |
| `enterprises.318.1.1.1.2.2.1.0` | Un ramo con i numeri che stanno sotto: un oggetto della MIB propria dell'apparato, mostrato con il suo numero. |

Sotto la casella, in sola lettura, l'OID nelle due forme:

| Lettura | Cosa mostra |
| --- | --- |
| **Nome nella MIB** | Il nome standard dell'oggetto con la sua istanza (`ifInOctets.2`), e sotto quello che la MIB dice dell'oggetto: la sua MIB, il tipo di valore che porta e se accetta la scrittura, come `IF-MIB · Counter32 · sola lettura` o `UPS-MIB · Integer32 · accetta la scrittura`. « Nessun nome standard » per un oggetto che il driver non conosce per nome. |
| **OID numerico** | L'OID in numeri, cioè quello che porta ogni richiesta. |

Un oggetto senza nome standard aggiunge la riga
« Un oggetto della MIB propria dell'apparato: compare con il suo numero, perché nessun file MIB viene letto. »
Un tag di cui il driver non può leggere l'OID non viene salvato, e la pagina del tag dice perché:

| Scrivi | La pagina del tag dice |
| --- | --- |
| Nessun OID | « OID è obbligatorio per questo driver. » |
| Un nome che il driver non conosce | « Questo nome non è uno degli oggetti MIB standard che il driver conosce. Scrivere l'OID in numeri. » |
| Una colonna senza la sua riga, come `ifInOctets` | « Una colonna di tabella ha bisogno dell'indice della sua riga, ad esempio ifInOctets.1. » |
| Un valore singolo con un'istanza diversa da 0, come `sysUpTime.1` | « Un valore singolo ha una sola istanza, .0, che si può omettere. » |
| Un ramo da solo, come `enterprises` o `ifTable` | « Un ramo dell'albero non nomina alcun valore. Scrivere i numeri dell'oggetto che sta sotto. » |
| Un primo numero oltre 2, un secondo di 40 o più, più di 128 numeri, o un numero oltre 4294967295 | « Un OID inizia con 0, 1 o 2 e un numero sotto 40, e ha al massimo 128 numeri fino a 4294967295. » |
| Qualsiasi altra cosa che non sia un OID | « Scrivere l'OID in numeri, ad esempio 1.3.6.1.2.1.1.3.0, oppure un nome standard con la sua istanza, ad esempio sysUpTime.0. » |

Il salvataggio applica la stessa regola:
« Il tag 'Battery status' non nomina alcun OID che il driver SNMP possa leggere. Aprirlo e correggere l'indirizzo che il pannello del tag segnala. »
La riga in sola lettura **Indirizzo di origine (bus)** mostra il numero che il driver riceve:
`1.3.6.1.2.1.33.1.2.1.0` per un tag scritto `upsBatteryStatus.0`.

### I nomi che il driver conosce {#the-names-the-driver-knows}

Il driver porta una tabella degli oggetti delle MIB standard che vale la pena nominare, scritta a
partire dalle RFC, così un nome significa la stessa cosa su ogni stazione. Nessun file MIB viene letto.

| MIB | Cosa nomina |
| --- | --- |
| SNMPv2-MIB (RFC 3418) | Il gruppo system: `sysDescr`, `sysObjectID`, `sysUpTime`, `sysContact`, `sysName`, `sysLocation`, `sysServices`. |
| IF-MIB (RFC 2863) | `ifNumber`, la tabella delle interfacce (`ifDescr`, `ifOperStatus`, `ifInOctets`, `ifOutErrors` e il resto) e la sua estensione con i contatori a 64 bit (`ifName`, `ifHCInOctets`, `ifHCOutOctets`, `ifHighSpeed`, `ifAlias`). |
| UPS-MIB (RFC 1628) | L'identità, la batteria, l'ingresso, l'uscita, il bypass, gli allarmi, il test, il controllo e la configurazione di un gruppo di continuità: `upsBatteryStatus`, `upsEstimatedChargeRemaining`, `upsOutputSource`, `upsOutputPercentLoad` e il resto. |
| ENTITY-SENSOR-MIB (RFC 3433) | La tabella dei sensori: `entPhySensorType`, `entPhySensorScale`, `entPhySensorValue`, `entPhySensorOperStatus` e il resto. |
| ENTITY-MIB (RFC 6933) | Il nome, la descrizione e la classe di un'entità fisica, che etichettano un sensore: `entPhysicalName`, `entPhysicalDescr`, `entPhysicalClass`. |
| HOST-RESOURCES-MIB (RFC 2790) | Il sistema (`hrSystemUptime`, `hrSystemProcesses`), la tabella dello storage (`hrStorageUsed`) e la tabella dei processori (`hrProcessorLoad`). |

`driver_capabilities` elenca ogni nome con il suo OID; vedi [Strumenti dell'agente](#agent-tools).

### Tipi di dato e accesso {#data-types-and-access}

L'elenco **Tipo di dato** offre solo ciò in cui l'oggetto si legge senza perdita:

| L'oggetto porta | Si legge più naturalmente come | Offerti anche |
| --- | --- | --- |
| Integer32, enumerazioni e TruthValue compresi | Int32 | Int64, Float, Double, String |
| Counter32, Gauge32, TimeTicks (centesimi di secondo) | UInt32 | Int64, Double, String |
| Counter64 | UInt64 | Double, String |
| DisplayString | String | |
| Byte, un indirizzo IP o un OID | String: i byte in esadecimale (`00:1A:2B`), l'indirizzo puntato, l'OID puntato | |
| Un oggetto senza nome standard | Float | Int32, UInt32, Int64, UInt64, Double, String: decide la risposta dell'agente alla lettura |

Un contatore non viene offerto come Float, che arrotonda oltre 16.777.216, né un Counter64 come Int64,
che rifiuterebbe un conteggio oltre la sua metà. Boolean non viene mai offerto: SNMP non ha booleani, e
il suo TruthValue (1 vero, 2 falso) e lo 0 e l'1 propri di un apparato leggerebbero lo stesso tipo in due
modi opposti, quindi uno stato si legge come Int32. Quando l'OID cambia, un tipo in cui il nuovo
oggetto non si legge diventa quello in cui si legge più naturalmente; e un tipo in cui non si legge
viene rifiutato, nominando quelli in cui si legge:
« ifHCOutOctets.2 si legge come uno di questi: UInt64, Double, String. »

Un oggetto standard che la sua MIB dichiara di sola lettura (i contatori, `sysUpTime`, gli stati) viene
offerto solo come **Sola lettura**, e il campo Accesso dice
« Sola lettura: il dispositivo riporta questo valore e nulla dall'esterno lo imposta. »
Un oggetto standard che la sua MIB dichiara scrivibile (`sysContact`, `sysName`, `sysLocation`,
`ifAdminStatus`, `ifAlias`, gli oggetti di test, controllo e configurazione della UPS-MIB) e un oggetto
della MIB propria dell'apparato ricevono ogni accesso: se l'agente accetta la scrittura è una sua
risposta.

## Lettura {#reading}

All'intervallo di interrogazione di ogni tag, la stazione manda un GET. Quello che l'agente risponde
decide cosa mostra il tag (vedi [La catena di conversione](connector-value-pipeline)):

| L'agente risponde | Cosa fa la lettura |
| --- | --- |
| Il valore | Il valore, nel tipo del tag, prima che le fasi del tag stesso lo convertano. Un testo che contiene un numero (`23.5`, che alcuni apparati scrivono) si legge in un tag numerico. |
| Un valore che il tipo del tag non può contenere, come un numero negativo in un UInt32 | Una lettura fallita di quel tag, con il motivo; il dispositivo continua a leggere gli altri tag. |
| noSuchObject o noSuchInstance, o un errore su quel solo oggetto | Una lettura fallita di quel tag, nominata con la risposta dell'agente; il dispositivo continua a leggere gli altri tag. In SNMPv1, dove un oggetto mancante fa rifiutare l'intera richiesta, il driver richiede senza di esso. |
| Nulla entro il timeout di risposta, dopo tutti i tentativi aggiuntivi | Silenzio: il dispositivo va offline e si riconnette, e la politica del tag per [un dispositivo che non ha risposto](connector-value-pipeline#the-device-did-not-answer) decide cosa mostra. La causa nomina l'agente, l'attesa e i tentativi, e ricorda che un agente tace anche davanti a una community o a un utente SNMPv3 che non accetta. |
| Un report SNMPv3 (un utente sconosciuto, una password o un protocollo sbagliati, un livello di sicurezza che l'agente non accetta), o la risposta dell'host che nessun agente ascolta sulla porta | Un errore di connessione con quella causa, nel diario tecnico e nell'ultimo errore del dispositivo; il dispositivo si riconnette. |

Un dispositivo fa una richiesta alla volta. Una lettura chiede l'oggetto del tag e, nella stessa
richiesta, gli altri tag del dispositivo che non hanno una risposta recente, fino a 32 OID; a un agente
che risponde che la richiesta è troppo grande (tooBig) ne viene mandata la metà da quel momento. Una
risposta portata così serve la lettura di un altro tag finché è più recente della metà dell'intervallo
di interrogazione di quel tag, così quaranta tag costano una o due richieste per passata. Il motore di
un agente SNMPv3 viene appreso una volta per connessione, e una richiesta che l'agente dichiara fuori
dalla sua finestra temporale viene inviata ancora una volta con i valori dell'agente stesso.

## Scrittura {#writing}

Un tag il cui accesso scrive manda un SET attraverso la coda del dispositivo. Una scrittura passa per lo
stesso imbuto di quella di ogni altro driver: la casella di scrittura prende il valore ingegneristico, e
le fasi di conversione vengono invertite prima che il valore grezzo sia inviato (vedi
[Connector](connector)). Il SET porta il tipo di valore con cui l'agente ha risposto per ultimo
all'oggetto; in mancanza, quello che dichiara la sua MIB; in mancanza ancora, quello che risponde ora un
GET; e per ultimo quello del tag stesso (un Int32 come Integer32, un UInt32 come Gauge32, uno String come
OCTET STRING). Un valore che quel tipo non può contenere viene rifiutato prima di inviare qualsiasi cosa.

| L'agente risponde | Cosa riporta la scrittura |
| --- | --- |
| Nessun errore | Fatto. Ogni risposta che il dispositivo conservava viene dimenticata, così la lettura seguente chiede di nuovo. |
| Uno stato di errore | « Scrittura rifiutata dall'apparecchiatura: `<reason>`. », con il motivo che nomina lo stato come lo scrive l'RFC 3416, come `notWritable (17)`, `wrongType (7)` o `wrongValue (10)`, e `readOnly (4)` in SNMPv1. |
| Nulla entro il timeout di risposta, dopo tutti i tentativi aggiuntivi | « Scrittura non confermata: l'apparecchiatura non ha risposto in tempo. » |

## Rilevamento {#discovery}

### La scheda Ambito della scansione {#the-scan-scope-card}

Per Configurare il connector, la pagina del driver porta la sua scheda **Ambito della scansione**,
sotto la riga
« Percorre i sottoalberi standard di un agente ed elenca ciò che trova. Un agente SNMPv3 si scansiona tramite il suo dispositivo: sceglilo come agente da scansionare. »

| Campo | Significato | Predefinito |
| --- | --- | --- |
| **Agente da scansionare** | **Un indirizzo scritto qui**, o un dispositivo del driver con il suo nome. L'agente di un dispositivo viene letto con l'host, la porta, la versione, le impostazioni e le credenziali come sono salvati, e una modifica del dispositivo che aspetta ancora di essere salvata viene salvata prima. È l'unico modo di scansionare un agente SNMPv3. | **Un indirizzo scritto qui** |
| **Indirizzo dell'agente** | Un agente scritto: il nome host o l'indirizzo IP, e la porta dopo i due punti quando non è quella sotto. | vuoto |
| **Porta** | Un agente scritto: da 1 a 65535. | 161 |
| **Versione SNMP** | Un agente scritto: SNMPv1 o SNMPv2c. | SNMPv2c |
| **Community** | Un agente scritto: la community a cui risponde, in una casella che nasconde ciò che si scrive, con `public` come suggerimento. Sotto: « Usata solo per questa scansione. Un dispositivo aggiunto dal risultato la conserva come sua community. » | vuoto |
| **Sottoalberi** | Una spunta ciascuno: **Sistema (SNMPv2-MIB)**, **Interfacce (IF-MIB)**, **Gruppo di continuità (UPS-MIB)**, **Sensori (ENTITY-SENSOR-MIB)** e **Risorse dell'host (HOST-RESOURCES-MIB)**. | tutti tranne Risorse dell'host |
| **Percorri anche** | « Un sottoalbero in più, in numeri o sotto un nome standard, ad esempio enterprises.318. Gli oggetti propri dell'apparato tornano come numeri. » | vuoto |

Quello che ancora manca all'ambito viene detto in rosso sotto la scheda, e Rileva resta in grigio
finché non è completo:

| L'ambito | La scheda dice |
| --- | --- |
| Un agente scritto senza indirizzo | « Scrivere l'indirizzo dell'agente SNMP da scansionare. » |
| Un agente scritto il cui indirizzo non è un host | « 'http://192.168.0.30' non è l'indirizzo di un agente SNMP. Scrivere il suo nome host o il suo indirizzo IP, con la porta se serve, per esempio 192.168.0.30 o 192.168.0.30:161. » |
| Un agente scritto senza community, o con una di più di 255 byte | « Scrivere la community a cui risponde l'agente, al massimo 255 byte. » |
| Un dispositivo che non esiste più | « Il dispositivo SNMP scelto per la scansione non esiste più. Scegliere un altro agente da scansionare. » |
| Un dispositivo senza il suo host o senza una credenziale che serve al suo agente | « Al dispositivo 'UPS room 1' mancano ancora l'host o una credenziale che serve al suo agente. Completa prima la sua scheda SNMP. » |
| Un sottoalbero da percorrere che non è un OID | « 'vendor' non è un OID da percorrere. Scriverlo in numeri o sotto un nome standard, ad esempio enterprises.318. » |
| Niente spuntato e niente indicato | « Spuntare almeno un sottoalbero, o indicarne uno da percorrere. » |

Quando il dispositivo da scansionare ha una modifica che non si può salvare, la scansione non parte:
« Il rilevamento non è partito perché non è stato possibile salvare la modifica del dispositivo da scansionare. »

### Cosa offre la scansione {#what-the-scan-offers}

Rileva chiede prima all'agente il suo nome (`sysName.0`), il che prova anche che l'agente risponde a
quelle credenziali, poi percorre ogni sottoalbero spuntato e quello indicato, con GETBULK in SNMPv2c e
SNMPv3 e GETNEXT in SNMPv1, finché l'agente non risponde fuori di esso. La riga di avanzamento conta
quello che ha letto:
« Percorso dell'agente SNMP a 192.168.10.40:161: 120 oggetti trovati. » Una scansione elenca al
massimo 2000 oggetti e percorre per al massimo 60 secondi; quando viene interrotta lì, o quando l'agente
tace a metà, conserva quello che ha trovato e lo dice:
« Il percorso di 192.168.10.40:161 si è fermato prima della fine, con 2000 oggetti trovati. Una scansione elenca al massimo 2000 oggetti, percorre per al massimo 60 s e si ferma dove l'agente tace. »

La scansione offre un candidato per agente, chiamato con il suo sysName (il nome del dispositivo o
l'host quando l'agente non ne dà), con la versione, il timeout e i tentativi aggiuntivi con cui è stato
letto, e gli oggetti trovati come tag candidati:

| Oggetto trovato | Nome del tag | Tipo di dato | Accesso |
| --- | --- | --- | --- |
| Un valore singolo che il driver conosce per nome | Il suo nome, senza il `.0`: `sysUpTime` | Quello in cui il valore risposto si legge più naturalmente | Lettura e scrittura dove la sua MIB lo dichiara scrivibile, Sola lettura negli altri casi |
| Una colonna di una tabella che il driver conosce per nome | Il suo nome e la sua riga: `ifInOctets.2` | Lo stesso | Lo stesso |
| Un oggetto della MIB propria dell'apparato | Il suo numero: `1.3.6.1.4.1.318.1.1.1.2.2.1.0` | Lo stesso | Sola lettura |

Un valore che nessun tipo di tag può contenere viene lasciato fuori. Un dispositivo aggiunto da una
scansione scritta conserva la community usata dalla scansione, protetta come ogni credenziale di
dispositivo; un dispositivo aggiunto dalla scansione di un dispositivo porta le credenziali di quel
dispositivo. Un candidato il cui agente è già letto da un dispositivo del driver (il dispositivo
scansionato, o un altro allo stesso host e alla stessa porta) viene segnato **Già configurato**: la sua
scheda elenca solo gli oggetti che nessun tag di quel dispositivo legge ancora, e un OID scritto con il
nome e con il numero conta come lo stesso, e **Aggiungi i tag**, prima di **Apri**, aggiunge quelli
spuntati a quel dispositivo. Il resto del comportamento della scansione è in
[Rilevamento](connector-discovery).

La pagina stessa di un dispositivo fa lo stesso senza la pagina del suo driver: **Rileva tag**, nell'intestazione della sua scheda **Tag**, percorre l'agente di quel dispositivo con le sue impostazioni e credenziali, sui sottoalberi standard e sul ramo del produttore che i suoi tag leggono già (`enterprises.318` per un tag sotto di esso), e offre solo gli oggetti per cui non ha ancora un tag (vedere [Rilevare i tag di un dispositivo](connector-discovery#discovering-a-devices-tags)).

## Esempio: un gruppo di continuità in SNMPv2c {#example-a-ups-over-snmpv2c}

Un gruppo di continuità con scheda di rete risponde in SNMPv2c a 192.168.10.40, con una community di
lettura impostata su quella scheda. Per leggerne la batteria:

1. Nella pagina del driver, **Aggiungi dispositivo**; chiamarlo `UPS room 1`, scrivere
   **Indirizzo host** 192.168.10.40 e lasciare **Porta** 161.
2. Nella scheda **Agente SNMP** lasciare SNMPv2c, scrivere la community di lettura della scheda in
   **Community**, e lasciare un **Timeout di risposta (ms)** di 2000 e 1 in **Tentativi aggiuntivi**. La
   riga che chiedeva la community sparisce.
3. **Aggiungi tag** `Battery status`, **OID** `upsBatteryStatus.0`, **Tipo di dato** Int32. Sotto la
   casella, il nome nella MIB dice upsBatteryStatus.0 con `UPS-MIB · Integer32 · sola lettura`, l'OID
   numerico 1.3.6.1.2.1.33.1.2.1.0, e l'accesso resta Sola lettura. Il valore è 1 unknown,
   2 batteryNormal, 3 batteryLow o 4 batteryDepleted.
4. **Aggiungi tag** `Battery charge`, **OID** `upsEstimatedChargeRemaining.0`, **Tipo di dato** Int32,
   **Unità** %.
5. Se il gruppo di continuità lo riporta, **Aggiungi tag** `Minutes remaining`, **OID**
   `upsEstimatedMinutesRemaining.0`, **Tipo di dato** Int32, **Unità** min.

La Base URI si legge `snmp://192.168.10.40:161?version=2c&timeoutMs=2000&retries=1`. Un agente fa lo
stesso con gli strumenti:

```
device_upsert name="UPS room 1" driver=Snmp host=192.168.10.40 snmpVersion=V2c snmpCommunity="<the UPS card's read community>"
tag_upsert device="UPS room 1" name="Battery status" address=upsBatteryStatus.0 opcUaType=Int32
tag_upsert device="UPS room 1" name="Battery charge" address=upsEstimatedChargeRemaining.0 opcUaType=Int32 unit=%
tag_upsert device="UPS room 1" name="Minutes remaining" address=upsEstimatedMinutesRemaining.0 opcUaType=Int32 unit=min
```

## Esempio: i contatori di interfaccia di uno switch in SNMPv3 {#example-a-switchs-interface-counters-over-snmpv3}

Uno switch gestito a 192.168.10.2 risponde in SNMPv3 per l'utente `scada`, configurato sullo switch con
autenticazione SHA-256 e cifratura AES-128. Per leggere il traffico e lo stato della sua porta 2:

1. **Aggiungi dispositivo**; chiamarlo `Core switch`, **Indirizzo host** 192.168.10.2, **Porta** 161.
2. Nella scheda **Agente SNMP** scegliere SNMPv3, scrivere `scada` in **Utente SNMPv3**, lasciare
   **Firmato e cifrato (authPriv)**, scegliere SHA-256 in **Protocollo di autenticazione** e scrivere la sua
   password, lasciare AES-128 in **Protocollo di cifratura** e scrivere la sua password: ognuna quella che lo
   switch conserva per `scada`, di almeno 8 caratteri.
3. **Aggiungi tag** `Port 2 in`, **OID** `ifHCInOctets.2`. Il tipo di dato diventa UInt64, il tipo in
   cui si legge un contatore a 64 bit, e l'elenco offre solo UInt64, Double e String; **Unità** B.
4. **Aggiungi tag** `Port 2 out`, **OID** `ifHCOutOctets.2`, UInt64, **Unità** B.
5. **Aggiungi tag** `Port 2 state`, **OID** `ifOperStatus.2`, **Tipo di dato** Int32: 1 up, 2 down,
   3 testing, 7 lowerLayerDown.

Il `.2` è l'indice dell'interfaccia sullo switch, quello che nomina `ifName.2`; una scansione del
sottoalbero delle interfacce elenca ogni interfaccia con il suo indice. La Base URI si legge
`snmp://192.168.10.2:161?version=3&security=authPriv&auth=sha256&priv=aes128&timeoutMs=2000&retries=1`.
Con gli strumenti, un `opcUaType` in cui l'oggetto non si legge, come Int32 su `ifHCOutOctets.2`, viene
rifiutato con i tipi in cui si legge:

```
device_upsert name="Core switch" driver=Snmp host=192.168.10.2 snmpVersion=V3 username=scada password="<authentication password>" snmpSecurityLevel=AuthPriv snmpAuthProtocol=Sha256 snmpPrivacyProtocol=Aes128 snmpPrivacyPassword="<privacy password>"
tag_upsert device="Core switch" name="Port 2 in" address=ifHCInOctets.2 opcUaType=UInt64 unit=B
tag_upsert device="Core switch" name="Port 2 out" address=ifHCOutOctets.2 opcUaType=UInt64 unit=B
tag_upsert device="Core switch" name="Port 2 state" address=ifOperStatus.2 opcUaType=Int32
```

## Strumenti dell'agente {#agent-tools}

`driver_capabilities` descrive questo driver sotto `snmp`: le versioni e le credenziali che ognuna
prende, i livelli di sicurezza e i protocolli, il timeout di risposta e i tentativi aggiuntivi, come si
scrive un OID, i tipi per genere di valore, ogni nome che il driver conosce con la sua MIB, il suo OID e
se accetta la scrittura, come si comportano letture e scritture, il rilevamento e i due esempi sopra.
`device_upsert driver=Snmp` prende `host`, `port` (161 di default), `snmpVersion` (`V1`, `V2c`, il
default, o `V3`), `snmpCommunity` in SNMPv1 e SNMPv2c (`''` la cancella), e in SNMPv3 `username`
(l'utente), `password` (la sua password di autenticazione, di almeno 8 caratteri), `snmpSecurityLevel`
(`AuthPriv`, il default, `AuthNoPriv` o `NoAuthNoPriv`), `snmpAuthProtocol` (`Md5`, `Sha1`, il default,
`Sha256`, `Sha384` o `Sha512`), `snmpPrivacyProtocol` (`Des`, `Aes128`, il default, `Aes192` o `Aes256`)
e `snmpPrivacyPassword`; con `responseTimeoutMs` (da 100 a 60000, 2000 di default) e `snmpRetries` (da 0
a 5, 1 di default). Una community su un dispositivo SNMPv3, o un campo SNMPv3 su un dispositivo a
community, viene rifiutato. Un dispositivo che gli strumenti restituiscono porta `snmp`: la versione,
`hasCommunity`, il livello di sicurezza e i protocolli in vigore, `hasPrivacyPassword`, il timeout, i
tentativi aggiuntivi e `missingCredential`, la credenziale che aspetta ancora; nessun segreto viene mai
restituito. `tag_upsert` prende l'OID come `address` e `opcUaType`, che di default è il tipo in cui
l'oggetto si legge più naturalmente; `wireQuantity` e `eipPath` vengono rifiutati.
`device_discover driver=Snmp` percorre o `target` (un host, con `port` quando non è 161) con
`snmpVersion` (`V1` o `V2c`) e `snmpCommunity`, o `snmpDevice`, il nome di un dispositivo del driver,
che è l'unico modo di scansionare un agente SNMPv3; `snmpSubtrees` sceglie i sottoalberi standard
(`System`, `Interfaces`, `Ups`, `Sensors`, `HostResources`, separati da virgole) e `snmpSubtree` ne
aggiunge uno. Gli strumenti non conservano la community di una scansione: un dispositivo creato da
quello che la scansione ha trovato la riceve di nuovo in `device_upsert`, e i tag che mancano a un
dispositivo configurato si aggiungono con `tag_upsert`. Gli altri strumenti sono in
[Strumenti dell'agente](agent-tools).

## Limiti da conoscere {#limits-worth-knowing}

- Le trap e gli inform, quello che l'apparato manda da sé quando succede qualcosa, non vengono
  ricevuti: ogni valore viene letto al suo intervallo di interrogazione, quindi una batteria che si
  scarica si vede alla lettura seguente del suo stato.
- Nessun file MIB viene importato. I nomi che il driver conosce sono quelli delle MIB standard che
  porta; un oggetto della MIB propria dell'apparato, sotto `enterprises`, si scrive e si mostra con il
  suo numero, e cosa significa si legge nella documentazione del costruttore.
- La stazione non è un agente SNMP: niente legge la stazione stessa in SNMP.
- Una scansione raggiunge un agente SNMPv3 solo tramite un dispositivo che conserva il suo utente e le
  sue password, e non prova da sé alcuna community né alcun utente.
- Una scansione elenca al massimo 2000 oggetti e percorre per al massimo 60 secondi: su uno switch
  grande, togli la spunta ai sottoalberi che non servono, o indica quello che serve.
- Nessun tag è un Boolean: un TruthValue o un acceso e spento proprio dell'apparato si legge come Int32.