# SNMP

> Equipamentos de rede que respondem SNMP v1, v2c ou v3 (nobreaks, PDUs, switches, roteadores, ar-condicionado de precisão e sensores de ambiente) lidos pelo seu agente no intervalo de leitura de cada tag: o cartão Agente SNMP, o OID de uma tag em números ou pelo nome padrão, os tipos de dado em que cada objeto é lido, leitura e escrita, a varredura que descobre os objetos de um agente e dois exemplos completos.

O driver **SNMP** lê e escreve os equipamentos de uma sala técnica pelo agente SNMP deles: nobreaks,
PDUs, switches, roteadores, ar-condicionado de precisão e sensores de temperatura ou umidade. Ele
completa o driver [Redfish](driver-redfish), que lê as controladoras de gerenciamento dos servidores:
juntos, os dois cobrem a sala técnica. Cada tag lê um objeto do agente pelo seu OID, como
`upsBatteryStatus.0` ou `ifHCInOctets.2`, e os valores chegam onde chegam os de toda outra tag: no
Logic, nos dashboards, nas execuções de uma bancada de teste do [Process](process).

A estação pergunta: cada tag é lida no seu intervalo de leitura, em SNMPv1, SNMPv2c ou SNMPv3, e o
**Intervalo de leitura (ms)** do cartão Dispositivo funciona como em qualquer driver, com cada tag
podendo sobrescrevê-lo. O que o equipamento manda por conta própria, os traps, não é recebido; veja
[Limites que vale conhecer](#limits-worth-knowing).

Um dispositivo deste driver é um agente, alcançado no seu host pela porta UDP 161. Os dispositivos
ficam sob o driver e podem ser arquivados em pastas, **Driver → Pasta → Dispositivo → Tag**, como em
todo driver sem linha serial nem broker.

## A página do driver {#the-drivers-page}

Para Configurar Connector, a página traz o cartão Escopo da varredura próprio do driver, com o agente
e as subárvores que o Descobrir percorre (veja [Descoberta](#discovery)). Abaixo dele fica a tabela
**Dispositivos** de qualquer driver (veja [A tabela de dispositivos](connector-drivers#the-device-table)),
que cresce com **Acrescentar dispositivo**, à direita do título; vazia, diz "Nenhum dispositivo ainda."
A barra do driver traz **Descobrir**, cinza até o cartão Escopo da varredura estar completo.

## Dispositivo {#device}

### Conexão {#connection}

| Campo | Significado | Padrão |
| --- | --- | --- |
| **Host ou IP** | O nome do host ou o endereço IP do agente. | vazio |
| **Porta** | A porta UDP em que o agente responde, de 1 a 65535. Uma caixa vazia mostra 161 em cinza e o agente é consultado nela. | 161 |

Um dispositivo novo não tem host: diz "Host ainda não informado", e nada é enviado até ele ter um.
A Base URI que o cabeçalho mostra é o endereço de runtime, com a versão, a segurança SNMPv3 em vigor,
o timeout de resposta e as novas tentativas:
`snmp://192.168.10.40:161?version=2c&timeoutMs=2000&retries=1`, ou
`snmp://192.168.10.2:161?version=3&security=authPriv&auth=sha256&priv=aes128&timeoutMs=2000&retries=1`.
Ela nunca leva a community, o usuário nem uma senha.

### O cartão Agente SNMP {#the-snmp-agent-card}

Abaixo do cartão Conexão, o cartão **Agente SNMP** diz como o agente é consultado. Os campos que ele
mostra seguem a versão e, no SNMPv3, o nível de segurança.

| Campo | Aparece | Significado | Padrão |
| --- | --- | --- | --- |
| **Versão do SNMP** | sempre | SNMPv1, SNMPv2c ou SNMPv3, cada uma com uma linha embaixo. SNMPv1: "O SNMPv1 não tem contadores de 64 bits, e um objeto que o agente não tem recusa a requisição inteira, que o driver então refaz sem ele." SNMPv2c: "O SNMPv2c lê os contadores de 64 bits, e um objeto que o agente não tem falha só naquela tag. A maioria dos equipamentos o responde." SNMPv3: "O SNMPv3 entra com um usuário, e assina e criptografa as mensagens conforme o nível de segurança." | SNMPv2c |
| **Community** | SNMPv1, SNMPv2c | A community a que o agente responde, com no máximo 255 bytes, numa caixa que esconde o que se digita; vazia, mostra `public` como dica, nunca como valor. Embaixo: "Um agente ignora uma requisição com uma community que ele não aceita, então uma community errada parece um agente que não responde." | vazio |
| **Usuário SNMPv3** | SNMPv3 | O usuário que o agente guarda, com no máximo 32 caracteres. | vazio |
| **Nível de segurança** | SNMPv3 | **Assinado e criptografado (authPriv)**: "Cada mensagem é assinada com a senha de autenticação e criptografada com a senha de privacidade." **Só assinado (authNoPriv)**: "Cada mensagem é assinada com a senha de autenticação e trafega sem criptografia." **Sem assinatura nem criptografia (noAuthNoPriv)**: "Só o nome de usuário é enviado: nada é assinado e nada é criptografado." | **Assinado e criptografado (authPriv)** |
| **Protocolo de autenticação** | SNMPv3, assinado | MD5, SHA-1, SHA-256, SHA-384 ou SHA-512. | SHA-1 |
| **Senha de autenticação** | SNMPv3, assinado | A senha que assina as mensagens. | vazio |
| **Protocolo de privacidade** | SNMPv3, authPriv | DES, AES-128, AES-192 ou AES-256. | AES-128 |
| **Senha de privacidade** | SNMPv3, authPriv | A senha que criptografa as mensagens. | vazio |
| **Timeout de resposta (ms)** | sempre | De 100 a 60000: "Quanto tempo uma requisição espera a resposta do agente antes de ser enviada de novo." | 2000 |
| **Novas tentativas** | sempre | De 0 a 5: "Quantas vezes uma requisição sem resposta é reenviada antes de o dispositivo contar como offline." | 1 |

Abaixo das duas senhas: "Cada senha é a que o agente guarda para este usuário, com pelo menos 8 caracteres."
O usuário, o nível de segurança e os dois protocolos são os que o agente tem configurados para esse
usuário, na página de configuração do próprio equipamento: a estação não tem como perguntá-los ao
agente. MD5, SHA-1 e DES são oferecidos porque muito equipamento instalado não aceita nada mais novo.

Uma credencial ainda não informada não é um erro: o dispositivo é salvo, o driver não manda nada ao
agente até ela existir, e uma linha calma abaixo do cartão diz o que falta, a primeira destas:

| Falta | O cartão diz |
| --- | --- |
| A community (SNMPv1, SNMPv2c) | "Informe a community a que o agente responde. Até lá, o dispositivo não envia nada." |
| O usuário (SNMPv3) | "Informe o usuário SNMPv3. Até lá, o dispositivo não envia nada." |
| A senha de autenticação (authNoPriv, authPriv) | "Informe a senha de autenticação. Até lá, o dispositivo não envia nada." |
| A senha de privacidade (authPriv) | "Informe a senha de privacidade. Até lá, o dispositivo não envia nada." |

Um dispositivo que tem o host e ainda não tem uma credencial não se conecta, e o último erro dele
nomeia a credencial que o agente espera. Um valor que o cartão não aceita não é salvo, e o cartão diz
por que, em vermelho:

| Você informa | O cartão diz |
| --- | --- |
| Uma senha de autenticação com menos de 8 caracteres | "A senha de autenticação precisa de pelo menos 8 caracteres." |
| Uma senha de privacidade com menos de 8 caracteres | "A senha de privacidade precisa de pelo menos 8 caracteres." |
| Um usuário com mais de 32 caracteres, ou uma community com mais de 255 bytes | "O usuário aceita no máximo 32 caracteres, e a community no máximo 255 bytes." |
| Um timeout de resposta fora de 100 a 60000, ou novas tentativas fora de 0 a 5 | A caixa volta ao valor em vigor e diz "Digite um número entre 100 e 60000." ou "Digite um número entre 0 e 5." |

O salvamento segue as mesmas regras do cartão, e o feed de ações avisa quando recusa:
"O dispositivo 'UPS room 1' tem uma configuração SNMP que o driver não consegue usar. Abra-o e corrija o campo que o painel marca."
A community e as duas senhas são guardadas como toda credencial de dispositivo (veja
[Credenciais e certificados](connector-devices#credentials-and-certificates)): protegidas em repouso
para a conta do Windows que as digitou, lacradas na exportação da configuração, e nunca mostradas na
Base URI, no diário nem na resposta de um agente. Uma credencial digitada em outra conta do Windows
volta vazia, e o dispositivo espera por ela como por uma nunca informada.

## Endereçamento da tag {#tag-addressing}

### O OID {#the-oid}

Uma tag deste driver lê um objeto do seu agente. O cartão Origem da tag traz a caixa **OID**, com a
dica "Um OID em números, por exemplo 1.3.6.1.2.1.1.3.0, ou um nome padrão com a sua instância, por exemplo sysUpTime.0, ifInOctets.2 ou upsBatteryStatus.0"
embaixo. Toda requisição leva o número, seja qual for a forma em que a tag é escrita:

| Escrito | Lido como |
| --- | --- |
| `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` | Esse número, que o painel chama de `sysUpTime.0`. |
| `sysUpTime.0`, `sysUpTime`, `SNMPv2-MIB::sysUpTime.0`, sem distinguir maiúsculas | Um valor único, cuja única instância `.0` pode ser omitida. |
| `ifInOctets.2` | Uma coluna de uma tabela com o índice da sua linha, aqui a interface 2, que é sempre escrito. |
| `enterprises.318.1.1.1.2.2.1.0` | Um ramo com os números abaixo dele: um objeto da MIB própria do equipamento, mostrado pelo número. |

Abaixo da caixa, só para leitura, o OID das duas formas:

| Leitura | O que mostra |
| --- | --- |
| **Nome na MIB** | O nome padrão do objeto com a sua instância (`ifInOctets.2`), e embaixo o que a MIB diz do objeto: a MIB, o tipo de valor que ele guarda e se aceita escrita, como `IF-MIB · Counter32 · somente leitura` ou `UPS-MIB · Integer32 · aceita escrita`. "Sem nome padrão" para um objeto que o driver não conhece pelo nome. |
| **OID numérico** | O OID em números, que é o que toda requisição leva. |

Um objeto sem nome padrão acrescenta a linha "Um objeto da MIB própria do equipamento: aparece pelo número, porque nenhum arquivo de MIB é lido."
Uma tag cujo OID o driver não consegue ler não é salva, e a página da tag diz por quê:

| Você informa | A página da tag diz |
| --- | --- |
| Nenhum OID | "OID é obrigatório para este driver." |
| Um nome que o driver não conhece | "Este nome não é um dos objetos MIB padrão que o driver conhece. Escreva o OID em números." |
| Uma coluna sem a sua linha, como `ifInOctets` | "Uma coluna de tabela precisa do índice da sua linha, por exemplo ifInOctets.1." |
| Um valor único com uma instância diferente de 0, como `sysUpTime.1` | "Um valor único tem uma só instância, .0, que pode ser omitida." |
| Um ramo sozinho, como `enterprises` ou `ifTable` | "Um ramo da árvore não nomeia um valor. Escreva os números do objeto abaixo dele." |
| Um primeiro número acima de 2, um segundo de 40 ou mais, mais de 128 números, ou um número acima de 4294967295 | "Um OID começa com 0, 1 ou 2 e um número abaixo de 40, e tem no máximo 128 números de até 4294967295." |
| Qualquer outra coisa que não seja um OID | "Escreva o OID em números, por exemplo 1.3.6.1.2.1.1.3.0, ou um nome padrão com a sua instância, por exemplo sysUpTime.0." |

O salvamento segue a mesma regra: "A tag 'Battery status' não nomeia um OID que o driver SNMP consiga ler. Abra-a e corrija o endereço que o painel da tag marca."
A linha só de leitura **Endereço de origem (barramento)** mostra o número que o driver recebe:
`1.3.6.1.2.1.33.1.2.1.0` para uma tag escrita `upsBatteryStatus.0`.

### Os nomes que o driver conhece {#the-names-the-driver-knows}

O driver traz uma tabela dos objetos das MIBs padrão que vale a pena nomear, escrita a partir das RFCs,
então um nome quer dizer a mesma coisa em toda estação. Nenhum arquivo de MIB é lido.

| MIB | O que ela nomeia |
| --- | --- |
| SNMPv2-MIB (RFC 3418) | O grupo system: `sysDescr`, `sysObjectID`, `sysUpTime`, `sysContact`, `sysName`, `sysLocation`, `sysServices`. |
| IF-MIB (RFC 2863) | `ifNumber`, a tabela de interfaces (`ifDescr`, `ifOperStatus`, `ifInOctets`, `ifOutErrors` e o resto) e a sua extensão com os contadores de 64 bits (`ifName`, `ifHCInOctets`, `ifHCOutOctets`, `ifHighSpeed`, `ifAlias`). |
| UPS-MIB (RFC 1628) | A identidade, a bateria, a entrada, a saída, o bypass, os alarmes, o teste, o controle e a configuração de um nobreak: `upsBatteryStatus`, `upsEstimatedChargeRemaining`, `upsOutputSource`, `upsOutputPercentLoad` e o resto. |
| ENTITY-SENSOR-MIB (RFC 3433) | A tabela de sensores: `entPhySensorType`, `entPhySensorScale`, `entPhySensorValue`, `entPhySensorOperStatus` e o resto. |
| ENTITY-MIB (RFC 6933) | O nome, a descrição e a classe de uma entidade física, que rotulam um sensor: `entPhysicalName`, `entPhysicalDescr`, `entPhysicalClass`. |
| HOST-RESOURCES-MIB (RFC 2790) | O sistema (`hrSystemUptime`, `hrSystemProcesses`), a tabela de armazenamento (`hrStorageUsed`) e a tabela de processadores (`hrProcessorLoad`). |

O `driver_capabilities` lista todos os nomes com o OID de cada um; veja
[Ferramentas do agente](#agent-tools).

### Tipos de dado e acesso {#data-types-and-access}

A lista **Tipo de dado** oferece só aquilo em que o objeto é lido sem perda:

| O objeto guarda | Lido de forma mais natural como | Também oferecidos |
| --- | --- | --- |
| Integer32, enumerações e TruthValue incluídos | Int32 | Int64, Float, Double, String |
| Counter32, Gauge32, TimeTicks (centésimos de segundo) | UInt32 | Int64, Double, String |
| Counter64 | UInt64 | Double, String |
| DisplayString | String | |
| Bytes, um endereço IP ou um OID | String: os bytes em hexadecimal (`00:1A:2B`), o endereço com pontos, o OID com pontos | |
| Um objeto sem nome padrão | Float | Int32, UInt32, Int64, UInt64, Double, String: a resposta do agente decide na leitura |

Um contador não é oferecido como Float, que arredonda acima de 16.777.216, e um Counter64 não é
oferecido como Int64, que recusaria uma contagem acima da metade. Boolean nunca é oferecido: o SNMP
não tem booleano, e o TruthValue dele (1 verdadeiro, 2 falso) e o 0 e 1 próprios de um equipamento
leriam o mesmo tipo de dois jeitos opostos, então um estado é lido como Int32. Quando o OID muda, um
tipo em que o novo objeto não é lido passa a ser aquele em que ele é lido de forma mais natural; e um
tipo em que ele não é lido é recusado, nomeando aqueles em que é:
"ifHCOutOctets.2 é lido como um destes: UInt64, Double, String."

Um objeto padrão que a MIB declara somente leitura (os contadores, `sysUpTime`, os estados) só é
oferecido como **Somente leitura**, e o campo Acesso diz "Somente leitura: o dispositivo informa este valor, e nada de fora o define."
Um objeto padrão que a MIB declara gravável (`sysContact`, `sysName`, `sysLocation`, `ifAdminStatus`,
`ifAlias`, os objetos de teste, controle e configuração da UPS-MIB) e um objeto da MIB própria do
equipamento recebem todos os acessos: se o agente aceita a escrita é resposta dele.

## Leitura {#reading}

No intervalo de leitura de cada tag, a estação manda um GET. O que o agente responde decide o que a
tag mostra (veja [A cadeia de valor](connector-value-pipeline)):

| O agente responde | O que a leitura faz |
| --- | --- |
| O valor | O valor, no tipo da tag, antes de os estágios da própria tag o converterem. Um texto que contém um número (`23.5`, que alguns equipamentos escrevem) é lido numa tag numérica. |
| Um valor que o tipo da tag não comporta, como um número negativo num UInt32 | Uma leitura com falha daquela tag, com o motivo; o dispositivo continua lendo as outras tags. |
| noSuchObject ou noSuchInstance, ou um erro só naquele objeto | Uma leitura com falha daquela tag, nomeada com a resposta do agente; o dispositivo continua lendo as outras tags. No SNMPv1, em que um objeto ausente recusa a requisição inteira, o driver pergunta de novo sem ele. |
| Nada dentro do timeout de resposta, depois de todas as novas tentativas | Silêncio: o dispositivo fica offline e reconecta, e a política da tag para [um dispositivo que não respondeu](connector-value-pipeline#the-device-did-not-answer) decide o que ela mostra. A causa nomeia o agente, a espera e as tentativas, e lembra que um agente também fica calado para uma community ou um usuário SNMPv3 que não aceita. |
| Um relatório SNMPv3 (um usuário desconhecido, uma senha ou um protocolo errados, um nível de segurança que o agente não aceita), ou a resposta do host de que nenhum agente escuta na porta | Uma falha de conexão com essa causa, no diário e no último erro do dispositivo; o dispositivo reconecta. |

Um dispositivo faz uma requisição por vez. Uma leitura pede o objeto da tag e, na mesma requisição,
as outras tags do dispositivo que não têm resposta recente, até 32 OIDs; um agente que responde que a
requisição é grande demais (tooBig) recebe metade disso dali em diante. Uma resposta trazida assim
serve a leitura de outra tag enquanto for mais nova que a metade do intervalo de leitura dessa tag,
então quarenta tags custam uma ou duas requisições por passada. O motor de um agente SNMPv3 é
aprendido uma vez por conexão, e uma requisição que o agente diz estar fora da sua janela de tempo é
enviada mais uma vez com os números do próprio agente.

## Escrita {#writing}

Uma tag cujo acesso escreve manda um SET pela fila do dispositivo. A escrita passa pelo mesmo funil da
de qualquer outro driver: a caixa de escrita recebe o valor de engenharia, e os estágios de conversão
são invertidos antes de o valor bruto ser enviado (veja [Connector](connector)). O SET leva o tipo de
valor com que o agente respondeu o objeto pela última vez; na falta dele, o que a MIB declara; na
falta deste, o que um GET responde agora; e por último o da própria tag (um Int32 como Integer32, um
UInt32 como Gauge32, uma String como OCTET STRING). Um valor que esse tipo não comporta é recusado
antes de qualquer envio.

| O agente responde | O que a escrita informa |
| --- | --- |
| Nenhum erro | Feito. Toda resposta que o dispositivo guardava é esquecida, então a próxima leitura pergunta de novo. |
| Um status de erro | "Escrita recusada pelo equipamento: `<reason>`.", com o motivo nomeando o status como a RFC 3416 o escreve, como `notWritable (17)`, `wrongType (7)` ou `wrongValue (10)`, e `readOnly (4)` no SNMPv1. |
| Nada dentro do timeout de resposta, depois de todas as novas tentativas | "Escrita não confirmada: o equipamento não respondeu a tempo." |

## Descoberta {#discovery}

### O cartão Escopo da varredura {#the-scan-scope-card}

Para Configurar Connector, a página do driver traz o seu cartão **Escopo da varredura**, sob a linha
"Percorre as subárvores padrão de um agente e lista o que encontra. Um agente SNMPv3 é varrido pelo seu dispositivo: escolha-o como o agente a varrer."

| Campo | Significado | Padrão |
| --- | --- | --- |
| **Agente a varrer** | **Um endereço digitado aqui**, ou um dispositivo do driver pelo nome. O agente de um dispositivo é lido com o host, a porta, a versão, as configurações e as credenciais como estão guardados, e uma edição do dispositivo que ainda espera ser salva é salva antes. É o único jeito de varrer um agente SNMPv3. | **Um endereço digitado aqui** |
| **Endereço do agente** | Um agente digitado: o nome do host ou o endereço IP, e a porta depois de dois-pontos quando não for a de baixo. | vazio |
| **Porta** | Um agente digitado: de 1 a 65535. | 161 |
| **Versão do SNMP** | Um agente digitado: SNMPv1 ou SNMPv2c. | SNMPv2c |
| **Community** | Um agente digitado: a community a que ele responde, numa caixa que esconde o que se digita, com `public` como dica. Embaixo: "Usada só nesta varredura. Um dispositivo adicionado a partir do resultado a guarda como community." | vazio |
| **Subárvores** | Uma marcação cada: **Sistema (SNMPv2-MIB)**, **Interfaces de rede (IF-MIB)**, **Nobreak (UPS-MIB)**, **Sensores (ENTITY-SENSOR-MIB)** e **Recursos do host (HOST-RESOURCES-MIB)**. | todas menos Recursos do host |
| **Percorrer também** | "Mais uma subárvore, em números ou abaixo de um nome padrão, por exemplo enterprises.318. Os objetos próprios do equipamento voltam como números." | vazio |

O que ainda falta ao escopo é dito em vermelho abaixo do cartão, e o Descobrir fica cinza até ele
estar completo:

| O escopo | O cartão diz |
| --- | --- |
| Um agente digitado sem endereço | "Digite o endereço do agente SNMP a varrer." |
| Um agente digitado cujo endereço não é um host | "'http://192.168.0.30' não é o endereço de um agente SNMP. Escreva o nome do host ou o endereço IP dele, com a porta se precisar, por exemplo 192.168.0.30 ou 192.168.0.30:161." |
| Um agente digitado sem community, ou com uma de mais de 255 bytes | "Digite a community a que o agente responde, com no máximo 255 bytes." |
| Um dispositivo que não existe mais | "O dispositivo SNMP escolhido para a varredura não existe mais. Escolha outro agente a varrer." |
| Um dispositivo sem o host ou sem uma credencial de que o agente precisa | "O dispositivo 'UPS room 1' ainda não tem o host ou uma credencial de que o agente precisa. Complete primeiro o cartão SNMP dele." |
| Uma subárvore a percorrer que não é um OID | "'vendor' não é um OID a percorrer. Escreva-o em números ou abaixo de um nome padrão, por exemplo enterprises.318." |
| Nada marcado e nada nomeado | "Marque pelo menos uma subárvore, ou indique uma a percorrer." |

Quando o dispositivo a varrer tem uma edição que não pode ser salva, a varredura não começa:
"A descoberta não começou porque a edição do dispositivo a varrer não pôde ser salva."

### O que a varredura oferece {#what-the-scan-offers}

O Descobrir primeiro pergunta ao agente o nome dele (`sysName.0`), o que também prova que o agente
responde a essas credenciais, e depois percorre cada subárvore marcada e a nomeada, com GETBULK no
SNMPv2c e no SNMPv3 e GETNEXT no SNMPv1, até o agente responder fora dela. A linha de progresso conta o
que leu: "Percorrendo o agente SNMP em 192.168.10.40:161: 120 objetos encontrados." Uma varredura lista
no máximo 2000 objetos e percorre por no máximo 60 segundos; quando é cortada ali, ou quando o agente
se cala no meio, ela guarda o que encontrou e diz isso:
"A leitura de 192.168.10.40:161 parou antes do fim, com 2000 objetos encontrados. Uma varredura lista no máximo 2000 objetos e percorre por no máximo 60 s, e para onde o agente se cala."

A varredura oferece um candidato por agente, com o nome do sysName dele (o nome do dispositivo ou o
host quando o agente não dá nenhum), com a versão, o timeout e as novas tentativas com que foi lido, e
os objetos que encontrou como tags candidatas:

| Objeto encontrado | Nome da tag | Tipo de dado | Acesso |
| --- | --- | --- | --- |
| Um valor único que o driver conhece pelo nome | O nome, sem o `.0`: `sysUpTime` | Aquele em que o valor respondido é lido de forma mais natural | Leitura e escrita onde a MIB o declara gravável, Somente leitura nos outros casos |
| Uma coluna de uma tabela que o driver conhece pelo nome | O nome e a linha: `ifInOctets.2` | O mesmo | O mesmo |
| Um objeto da MIB própria do equipamento | O número: `1.3.6.1.4.1.318.1.1.1.2.2.1.0` | O mesmo | Somente leitura |

Um valor que nenhum tipo de tag comporta fica de fora. Um dispositivo adicionado a partir de uma
varredura digitada guarda a community que a varredura usou, protegida como toda credencial de
dispositivo; um dispositivo adicionado a partir da varredura de um dispositivo leva as credenciais
desse dispositivo. Um candidato cujo agente um dispositivo do driver já lê (o dispositivo varrido, ou
outro no mesmo host e porta) é marcado **Já configurado**: o cartão dele lista só os objetos que
nenhuma tag desse dispositivo lê ainda, um OID escrito pelo nome e pelo número contando como o mesmo,
e **Acrescentar tags**, antes de **Abrir**, acrescenta os marcados a esse dispositivo. O resto do
comportamento da varredura está em [Descoberta](connector-discovery).

A própria página de um dispositivo faz o mesmo sem a página do driver: **Descobrir tags**, no cabeçalho do cartão **Tags** dele, caminha pelo agente daquele dispositivo com as configurações e credenciais dele, pelas subárvores padrão e pelo ramo do fabricante que as tags dele já leem (`enterprises.318` para uma tag abaixo dele), e oferece só os objetos para os quais ele ainda não tem tag (veja [Descobrir as tags de um dispositivo](connector-discovery#discovering-a-devices-tags)).

## Exemplo: um nobreak por SNMPv2c {#example-a-ups-over-snmpv2c}

Um nobreak com placa de rede responde SNMPv2c em 192.168.10.40, com uma community de leitura definida
nessa placa. Leia a bateria dele:

1. Na página do driver, **Acrescentar dispositivo**; dê o nome `UPS room 1`, informe **Host ou IP**
   192.168.10.40 e mantenha **Porta** 161.
2. No cartão **Agente SNMP** mantenha SNMPv2c, digite a community de leitura da placa em
   **Community**, e mantenha um **Timeout de resposta (ms)** de 2000 e 1 em **Novas tentativas**.
   A linha que pedia a community some.
3. **Acrescentar tag** `Battery status`, **OID** `upsBatteryStatus.0`, **Tipo de dado** Int32. Abaixo
   da caixa, o nome na MIB diz upsBatteryStatus.0 com `UPS-MIB · Integer32 · somente leitura`, o OID
   numérico 1.3.6.1.2.1.33.1.2.1.0, e o acesso fica em Somente leitura. O valor é 1 unknown,
   2 batteryNormal, 3 batteryLow ou 4 batteryDepleted.
4. **Acrescentar tag** `Battery charge`, **OID** `upsEstimatedChargeRemaining.0`, **Tipo de dado**
   Int32, **Unidade** %.
5. Se o nobreak informar, **Acrescentar tag** `Minutes remaining`, **OID**
   `upsEstimatedMinutesRemaining.0`, **Tipo de dado** Int32, **Unidade** min.

A Base URI diz `snmp://192.168.10.40:161?version=2c&timeoutMs=2000&retries=1`. Um agente faz o mesmo
com as ferramentas:

```
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
```

## Exemplo: os contadores de interface de um switch por SNMPv3 {#example-a-switchs-interface-counters-over-snmpv3}

Um switch gerenciável em 192.168.10.2 responde SNMPv3 para o usuário `scada`, configurado no switch
com autenticação SHA-256 e privacidade AES-128. Leia o tráfego e o estado da porta 2 dele:

1. **Acrescentar dispositivo**; dê o nome `Core switch`, **Host ou IP** 192.168.10.2, **Porta** 161.
2. No cartão **Agente SNMP** escolha SNMPv3, digite `scada` em **Usuário SNMPv3**, mantenha
   **Assinado e criptografado (authPriv)**, escolha SHA-256 em **Protocolo de autenticação** e digite
   a senha dele, mantenha AES-128 em **Protocolo de privacidade** e digite a senha dele: cada uma a
   que o switch guarda para `scada`, com pelo menos 8 caracteres.
3. **Acrescentar tag** `Port 2 in`, **OID** `ifHCInOctets.2`. O tipo de dado passa a UInt64, o tipo
   em que um contador de 64 bits é lido, e a lista oferece só UInt64, Double e String; **Unidade** B.
4. **Acrescentar tag** `Port 2 out`, **OID** `ifHCOutOctets.2`, UInt64, **Unidade** B.
5. **Acrescentar tag** `Port 2 state`, **OID** `ifOperStatus.2`, **Tipo de dado** Int32: 1 up,
   2 down, 3 testing, 7 lowerLayerDown.

O `.2` é o índice da interface no switch, o que `ifName.2` nomeia; uma varredura da subárvore de
interfaces lista cada interface com o seu índice. A Base URI diz
`snmp://192.168.10.2:161?version=3&security=authPriv&auth=sha256&priv=aes128&timeoutMs=2000&retries=1`.
Com as ferramentas, um `opcUaType` em que o objeto não é lido, como Int32 em `ifHCOutOctets.2`, é
recusado com os tipos em que ele é lido:

```
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
```

## Ferramentas do agente {#agent-tools}

O `driver_capabilities` descreve este driver em `snmp`: as versões e as credenciais que cada uma
recebe, os níveis de segurança e os protocolos, o timeout de resposta e as novas tentativas, como um
OID é escrito, os tipos por espécie de valor, todos os nomes que o driver conhece com a MIB, o OID e se
aceitam escrita, como leituras e escritas se comportam, a descoberta e os dois exemplos acima.
O `device_upsert driver=Snmp` recebe `host`, `port` (161 por padrão), `snmpVersion` (`V1`, `V2c`, o
padrão, ou `V3`), `snmpCommunity` no SNMPv1 e no SNMPv2c (`''` a apaga), e no SNMPv3 `username` (o
usuário), `password` (a senha de autenticação, com pelo menos 8 caracteres), `snmpSecurityLevel`
(`AuthPriv`, o padrão, `AuthNoPriv` ou `NoAuthNoPriv`), `snmpAuthProtocol` (`Md5`, `Sha1`, o padrão,
`Sha256`, `Sha384` ou `Sha512`), `snmpPrivacyProtocol` (`Des`, `Aes128`, o padrão, `Aes192` ou
`Aes256`) e `snmpPrivacyPassword`; com `responseTimeoutMs` (de 100 a 60000, 2000 por padrão) e
`snmpRetries` (de 0 a 5, 1 por padrão). Uma community num dispositivo SNMPv3, ou um campo SNMPv3 num
dispositivo de community, é recusado. Um dispositivo que as ferramentas devolvem traz `snmp`: a versão,
`hasCommunity`, o nível de segurança e os protocolos em vigor, `hasPrivacyPassword`, o timeout, as
novas tentativas e `missingCredential`, a credencial que ele ainda espera; nenhum segredo é devolvido.
O `tag_upsert` recebe o OID como `address` e `opcUaType`, que por padrão é o tipo em que o objeto é
lido de forma mais natural; `wireQuantity` e `eipPath` são recusados. O `device_discover driver=Snmp`
percorre ou `target` (um host, com `port` quando não for 161) com `snmpVersion` (`V1` ou `V2c`) e
`snmpCommunity`, ou `snmpDevice`, o nome de um dispositivo do driver, que é o único jeito de varrer um
agente SNMPv3; `snmpSubtrees` escolhe as subárvores padrão (`System`, `Interfaces`, `Ups`, `Sensors`,
`HostResources`, separadas por vírgula) e `snmpSubtree` acrescenta mais uma. As ferramentas não
guardam uma community de varredura: um dispositivo criado a partir do que a varredura encontrou a
recebe de novo no `device_upsert`, e as tags que faltam a um dispositivo configurado são acrescentadas
com `tag_upsert`. As outras ferramentas estão em [Ferramentas do agente](agent-tools).

## Limites que vale conhecer {#limits-worth-knowing}

- Traps e informs, o que o equipamento manda por conta própria quando algo acontece, não são
  recebidos: cada valor é lido no seu intervalo de leitura, então uma bateria que fica fraca é vista
  na próxima leitura do seu estado.
- Nenhum arquivo de MIB é importado. Os nomes que o driver conhece são os das MIBs padrão que ele
  traz; um objeto da MIB própria do equipamento, sob `enterprises`, é escrito e mostrado pelo número,
  e o que ele significa se lê na documentação do fabricante.
- A estação não é um agente SNMP: nada lê a própria estação por SNMP.
- Uma varredura só alcança um agente SNMPv3 por um dispositivo que guarda o usuário e as senhas dele,
  e não tenta nenhuma community nem usuário por conta própria.
- Uma varredura lista no máximo 2000 objetos e percorre por no máximo 60 segundos: num switch grande,
  desmarque as subárvores que não servem, ou nomeie a que serve.
- Nenhuma tag é Boolean: um TruthValue ou um ligado e desligado próprio do equipamento é lido como
  Int32.