Módulo SNMP

O módulo snmp fornece uma interface completa para monitoramento e gerenciamento de dispositivos de rede através do protocolo SNMP (Simple Network Management Protocol). Este módulo é útil para coleta de métricas de roteadores, switches, servidores, impressoras e qualquer dispositivo que suporte SNMP.
Suporte a SNMP v1, v2c e v3
Operações GET, GET BULK e WALK
Autenticação e criptografia SNMP v3
Configuração flexível de timeout e retentativas
Retorno seguro com tratamento de erros
Protocolos suportados:

SNMP v1: Protocolo básico com comunidade pública/privada

SNMP v2c: Melhorias de performance com operações BULK

SNMP v3: Segurança avançada com autenticação e criptografia
Configuração SNMP
Todas as funções SNMP requerem um objeto de configuração que define os parâmetros de conexão. A configuração é uma tabela Lua com os seguintes campos:
Campos de Configuração Básicos:
Campo
Tipo
Padrão
Descrição
address
string
obrigatório
Endereço IP ou hostname do dispositivo
snmpVersion
número
1
Versão SNMP (1=v1, 2=v2c, 3=v3)
snmpPort
número
161
Porta SNMP
snmpCommunity
string
nil
Comunidade SNMP (v1/v2c)
snmpTimeout
número
5
Timeout em segundos
snmpRetryCount
número
3
Número de retentativas
snmpMaxBulkItems
número
nil
Máximo de itens por operação BULK
snmpExponentialBackoff
booleano
false
Habilitar backoff exponencial
Campos para SNMP v3:
Campo
Tipo
Descrição
snmpSecurityLevel
string
Nível de segurança: "NoAuthNoPriv", "AuthNoPriv", "AuthPriv"
snmpAuthProtocol
string
Protocolo de autenticação: "MD5", "SHA1"
snmpAuthUser
string
Usuário de autenticação
snmpAuthPassword
string
Senha de autenticação
snmpPrivProtocol
string
Protocolo de criptografia: "DES", "AES"
snmpPrivPassword
string
Senha de criptografia
Configuração via Tabela params:
O ambiente Lua inclui uma tabela predefinida chamada params que contém os detalhes do dispositivo atual. Esta tabela pode ser usada diretamente como configuração SNMP, pois já possui os campos necessários no formato esperado.
Exemplo de uso direto:
-- Usar a tabela device diretamente como configuração
local sys_descr = snmp.getex(device, "1.3.6.1.2.1.1.1.0")
print("Descrição do dispositivo:", sys_descr)

-- Versão que não lança erro
local valor, erro = snmp.get_safe(device, "1.3.6.1.2.1.1.3.0")
if not erro then
 print("Uptime do dispositivo:", valor)
end

Combinando com configurações adicionais:
-- Criar configuração baseada em device com ajustes
local config = {
 address = device.address,
 snmpVersion = device.snmpVersion,
 snmpCommunity = device.snmpCommunity,
 snmpTimeout = device.snmpTimeout or 5, -- Usar padrão se não definido
 snmpRetryCount = 2, -- Sobrescrever valor padrão
 snmpMaxBulkItems = 50 -- Adicionar configuração extra
}

-- Usar para operação BULK
local oids = {"1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.3.0"}
local resultados = snmp.get_bulk(config, oids)

Exemplos de Configuração:
-- Configuração básica SNMP v2c
local config_v2c = {
 address = "192.168.1.1",
 snmpVersion = 2,
 snmpCommunity = "public",
 snmpTimeout = 3,
 snmpRetryCount = 2
}

-- Configuração SNMP v3 com autenticação e criptografia
local config_v3 = {
 address = "10.0.0.254",
 snmpVersion = 3,
 snmpSecurityLevel = "AuthPriv",
 snmpAuthProtocol = "SHA1",
 snmpAuthUser = "monitor",
 snmpAuthPassword = "senha123",
 snmpPrivProtocol = "AES",
 snmpPrivPassword = "chave456",
 snmpTimeout = 5
}

-- Configuração para dispositivo com porta não padrão
local config_custom_port = {
 address = "switch.piso1.local",
 snmpVersion = 2,
 snmpCommunity = "internal",
 snmpPort = 8161, -- Porta customizada
 snmpTimeout = 10 -- Timeout maior para rede lenta
}

Funções Disponíveis
1. snmp.getex(config, oid)
Realiza uma consulta SNMP GET para um OID específico.
Parâmetros:

config (tabela): Configuração SNMP (ver seção acima)

oid (string): OID a ser consultado (formato numérico ou nomeado)
Retorno:

valor: Valor retornado pelo dispositivo SNMP (número, string, etc.)
Erros:
Lança erro se o OID não existir ou houver falha na comunicação
Exemplo de Uso:
-- Consultar sysDescr (descrição do sistema)
local config = {
 address = "192.168.1.1",
 snmpVersion = 2,
 snmpCommunity = "public"
}

local sys_descr = snmp.getex(config, "1.3.6.1.2.1.1.1.0")
-- ou usando OID nomeado
local sys_descr = snmp.getex(config, ".1.3.6.1.2.1.1.1.0")

print("Descrição do sistema:", sys_descr)
-- Exemplo de saída: "Cisco IOS Software, C3750 Software (C3750-IPSERVICESK9-M), Version 12.2(55)SE10, RELEASE SOFTWARE (fc2)"

-- Consultar uptime do sistema
local sys_uptime = snmp.getex(config, "1.3.6.1.2.1.1.3.0")
print("Uptime:", sys_uptime, "centésimos de segundo")

-- Consultar nome do host
local sys_name = snmp.getex(config, "1.3.6.1.2.1.1.5.0")
print("Nome do host:", sys_name)

-- Consultar localização
local sys_location = snmp.getex(config, "1.3.6.1.2.1.1.6.0")
print("Localização:", sys_location)

2. snmp.get_safe(config, oid)
Versão segura de getex que não lança exceções, retornando erro como segundo valor.
Parâmetros:

config (tabela): Configuração SNMP

oid (string): OID a ser consultado
Retorno:

tuple: (valor, erro) onde:

valor (qualquer tipo ou nil): Valor retornado se bem-sucedido

erro (string ou nil): Mensagem de erro se falhar, nil se bem-sucedido

Exemplo de Uso:
local config = {
 address = "192.168.1.1",
 snmpVersion = 2,
 snmpCommunity = "public"
}

-- Consulta segura que não quebra o script em caso de erro
local valor, erro = snmp.get_safe(config, "1.3.6.1.2.1.1.1.0")

if erro then
 log.error("Falha na consulta SNMP:", erro)
 -- Tomar ação alternativa
else
 print("Valor obtido:", valor)
end

-- Consultar múltiplos OIDs com tratamento de erro individual
local oids = {
 "1.3.6.1.2.1.1.1.0", -- sysDescr
 "1.3.6.1.2.1.1.3.0", -- sysUpTime
 "1.3.6.1.2.1.1.5.0", -- sysName
 "1.3.6.1.2.1.1.6.0" -- sysLocation
}

local resultados = {}
for _, oid in ipairs(oids) do
 local valor, erro = snmp.get_safe(config, oid)
 if erro then
 log.warn("Falha no OID", oid, ":", erro)
 resultados[oid] = {erro = erro}
 else
 resultados[oid] = {valor = valor}
 end
end

3. snmp.get_bulk(config, oids)
Realiza operação SNMP GET BULK para múltiplos OIDs de uma vez (SNMP v2c/v3).
Parâmetros:

config (tabela): Configuração SNMP (deve ser v2 ou v3)

oids (array de strings): Lista de OIDs para consulta
Retorno:

tabela: Mapa OID → valor para todos os OIDs consultados
Comportamento:
Mais eficiente que múltiplas chamadas getex para muitos OIDs
Suportado apenas em SNMP v2c e v3
Usa snmpMaxBulkItems da configuração para limitar tamanho
Exemplo de Uso:
local config = {
 address = "192.168.1.1",
 snmpVersion = 2, -- Deve ser v2 ou v3 para GET BULK
 snmpCommunity = "public",
 snmpMaxBulkItems = 50 -- Limitar a 50 OIDs por operação
}

-- Consultar múltiplas informações do sistema de uma vez
local oids = {
 "1.3.6.1.2.1.1.1.0", -- sysDescr
 "1.3.6.1.2.1.1.3.0", -- sysUpTime
 "1.3.6.1.2.1.1.5.0", -- sysName
 "1.3.6.1.2.1.1.6.0", -- sysLocation
 "1.3.6.1.2.1.1.7.0" -- sysServices
}

local resultados = snmp.get_bulk(config, oids)

for oid, valor in pairs(resultados) do
 print("OID:", oid, "=", valor)
end

-- Consultar informações de múltiplas interfaces
local function obter_info_interfaces(config, indices)
 local oids = {}
 for _, idx in ipairs(indices) do
 table.insert(oids, "1.3.6.1.2.1.2.2.1.2." .. idx) -- ifDescr
 table.insert(oids, "1.3.6.1.2.1.2.2.1.3." .. idx) -- ifType
 table.insert(oids, "1.3.6.1.2.1.2.2.1.5." .. idx)
 end
 return snmp.get_bulk(config, oids)
end

4. snmp.get(oid)
Versão simplificada de snmp.getex que usa automaticamente a configuração do dispositivo atual (params).
Parâmetros:

oid (string): OID a ser consultado
Retorno:

valor: Valor retornado pelo dispositivo SNMP
Comportamento:
Usa params como configuração
Lança erro se o OID não existir ou houver falha na comunicação
Exemplo de Uso:
-- Consulta simplificada usando a configuração do dispositivo atual
local sys_descr = snmp.get("1.3.6.1.2.1.1.1.0")
print("Descrição do sistema:", sys_descr)

-- Consultar múltiplos OIDs
local uptime = snmp.get("1.3.6.1.2.1.1.3.0")
local hostname = snmp.get("1.3.6.1.2.1.1.5.0")

print("Uptime:", uptime, "Hostname:", hostname)

5. snmp.walk(oid, cache_ttl, enforce_ordering)
Realiza uma operação SNMP WALK com suporte a cache e ordenação.
Parâmetros:

oid (string): OID base para o walk

cache_ttl (número, opcional): Tempo de vida do cache em segundos

enforce_ordering (booleano, opcional): Forçar ordenação dos resultados (ordem natural)
Comportamento do cache:
Usa cache quando cache_ttl é especificado
Exemplo de Uso:
-- Walk com cache de 30 segundos
local interfaces = snmp.walk("1.3.6.1.2.1.2.2.1.2", 30)
for oid, ifname in pairs(interfaces) do
 print("Interface", oid, ":", ifname)
end

-- Walk com ordenação forçada (sem cache)
local ordered_interfaces = snmp.walk("1.3.6.1.2.1.2.2.1.2", nil, true)
print("Total de interfaces:", #ordered_interfaces)

Comportamento de Ordenação:
O parâmetro enforce_ordering controla como os resultados são estruturados:

Quando false (padrão): Os resultados são retornados como uma tabela Lua onde cada OID é uma chave que mapeia para seu valor. Esta estrutura é eficiente para acesso aleatório, mas perde a ordenação natural dos OIDs, pois as tabelas Lua não preservam a ordem de inserção das chaves.

Quando true: Os resultados são retornados como uma lista de pares (tabela de tabelas), onde cada elemento é uma tabela contendo 2 elementos. Esta estrutura preserva a ordem natural dos OIDs conforme retornados pelo dispositivo SNMP.

Exemplo de diferença:
-- Com enforce_ordering = false (padrão)
local resultado_tabela = snmp.walk("1.3.6.1.2.1.2.2.1.2", nil, false)
-- Estrutura: { ["1.3.6.1.2.1.2.2.1.2.1"] = "eth0", ["1.3.6.1.2.1.2.2.1.2.2"] = "eth1" }
-- A ordem das chaves não é garantida

-- Com enforce_ordering = true
local resultado_lista = snmp.walk("1.3.6.1.2.1.2.2.1.2", nil, true)
-- Estrutura: { {"1.3.6.1.2.1.2.2.1.2.1", "eth0"},
-- {"1.3.6.1.2.1.2.2.1.2.2", "eth1"} }
-- A ordem dos elementos é preservada

Quando usar cada modo:
Use enforce_ordering = false quando você só precisa acessar valores por OID específico e a ordem não importa.
Use enforce_ordering = true quando você precisa processar os resultados na mesma ordem em que foram retornados pelo dispositivo, como para:
Gerar relatórios ordenados
Processar sequências de índices consecutivos
Manter correspondência com outras listas ordenadas

Retorno:

tabela: Mapa OID → valor para todos os OIDs encontrados
6. snmp.walkex(device, oid, cache_ttl)
Função estendida de walk com sistema de cache avançado e prevenção de execuções concorrentes.
Parâmetros:

device (tabela): Configuração do dispositivo

oid (string): OID base para o walk

cache_ttl (número, opcional): Tempo de vida do cache em segundos
Retorno:

tabela: Mapa OID → valor para todos os OIDs encontrados
Comportamento:
Implementa cache global compartilhado entre execuções
Previne execuções concorrentes do mesmo walk
Usa registry para coordenar execuções simultâneas
Exemplo de Uso:
-- Walk estendido com cache de 60 segundos
local device_config = {
 address = "192.168.1.1",
 snmpVersion = 2,
 snmpCommunity = "public"
}

local sys_oids = snmp.walkex(device_config, "1.3.6.1.2.1.1", 60)
for oid, value in pairs(sys_oids) do
 print("OID:", oid, "Valor:", value)
end

7. snmp.count(oid)
Conta o número de itens retornados por um walk.
Parâmetros:

oid (string): OID base para contar
Retorno:

número: Quantidade de itens encontrados
Exemplo de Uso:
-- Contar número de interfaces
local num_interfaces = snmp.count("1.3.6.1.2.1.2.2.1.2")
print("Número de interfaces:", num_interfaces)

-- Contar número de processos
local num_processes = snmp.count("1.3.6.1.2.1.25.4.2.1.2")
print("Número de processos:", num_processes)

8. snmp.diff(typ, lhs, rhs)
Calcula a diferença entre dois valores, tratando rollover de contadores.
Parâmetros:

typ (número): Tipo do contador (32 ou 64 bits)

lhs (número): Valor atual

rhs (número): Valor anterior
Retorno:

número: Diferença entre os valores
Comportamento:
Trata rollover de contadores de 32 e 64 bits
Sinaliza RepeatPrevValue se a diferença for negativa
Exemplo de Uso:
-- Calcular diferença para contador de 32 bits
local current_bytes = snmp.get("1.3.6.1.2.1.2.2.1.10.1") -- ifInOctets.1
local prev_bytes = prev("1.3.6.1.2.1.2.2.1.10.1")
local bytes_diff = snmp.diff(32, current_bytes, prev_bytes)

print("Bytes recebidos desde última leitura:", bytes_diff)

9. inst(oid)
Resolve dinamicamente OIDs de instâncias baseado no nome da instância.
Parâmetros:

oid (string): OID base (sem índice de instância)
Retorno:

string: OID completo com índice de instância
Comportamento:
Usa params.InstanceName e params.snmpOIDDesc para resolução
Suporta cache de instâncias
Lança erro se a instância não for encontrada
Exemplo de Uso:
-- Resolver OID para instância específica
-- params.InstanceName = "eth0"
-- params.snmpOIDDesc = "1.3.6.1.2.1.2.2.1.2" -- ifDescr

local if_in_octets_oid = inst("1.3.6.1.2.1.2.2.1.10") -- ifInOctets
print("OID resolvido:", if_in_octets_oid)
-- Saída: "1.3.6.1.2.1.2.2.1.10.1" (se eth0 for índice 1)

-- Consultar usando OID resolvido
local bytes_in = snmp.get(if_in_octets_oid)
print("Bytes recebidos na interface eth0:", bytes_in)

10. prev(oid)
Obtém o valor anterior de um OID armazenado.
Parâmetros:

oid (string): OID para obter valor anterior
Retorno:

qualquer tipo: Valor anterior armazenado, ou 0 se não existir
Comportamento:
Busca valor em store.get("snmp.value." .. oid)

Retorna 0 se não encontrar valor armazenado
Exemplo de Uso:
-- Obter valor anterior para cálculo de taxa
local current_value = snmp.get("1.3.6.1.2.1.2.2.1.16.1") -- ifOutOctets.1
local previous_value = prev("1.3.6.1.2.1.2.2.1.16.1")

local bytes_out_diff = current_value - previous_value
print("Bytes enviados desde última leitura:", bytes_out_diff)

11. lapsed(oid)
Obtém o tempo decorrido desde a última leitura de um OID.
Parâmetros:

oid (string): OID para verificar tempo decorrido
Retorno:

número: Tempo em segundos desde última leitura, ou 1 se não houver registro
Exemplo de Uso:
-- Calcular taxa por segundo
local current_counter = snmp.get("1.3.6.1.2.1.2.2.1.10.1") -- ifInOctets.1
local previous_counter = prev("1.3.6.1.2.1.2.2.1.10.1")
local time_elapsed = lapsed("1.3.6.1.2.1.2.2.1.10.1")

local bytes_per_second = (current_counter - previous_counter) / time_elapsed
print("Taxa de recebimento:", bytes_per_second, "bytes/segundo")

Exemplos Completos
Monitoramento de Interface de Rede:
-- Resolver OID da interface eth0
local if_index_oid = inst("1.3.6.1.2.1.2.2.1.1") -- ifIndex
local if_descr_oid = inst("1.3.6.1.2.1.2.2.1.2") -- ifDescr

-- Obter informações da interface
local interface_index = snmp.get(if_index_oid)
local interface_name = snmp.get(if_descr_oid)

print("Monitorando interface:", interface_name, "(índice", interface_index, ")")

-- Coletar estatísticas
local in_octets = snmp.get(inst("1.3.6.1.2.1.2.2.1.10")) -- ifInOctets
local out_octets = snmp.get(inst("1.3.6.1.2.1.2.2.1.16")) -- ifOutOctets
local in_errors = snmp.get(inst("1.3.6.1.2.1.2.2.1.14")) -- ifInErrors
local out_errors = snmp.get(inst("1.3.6.1.2.1.2.2.1.20")) -- ifOutErrors

-- Calcular diferenças desde última leitura
local time_elapsed = lapsed(inst("1.3.6.1.2.1.2.2.1.10"))
local prev_in = prev(inst("1.3.6.1.2.1.2.2.1.10"))
local prev_out = prev(inst("1.3.6.1.2.1.2.2.1.16"))

local in_rate = (in_octets - prev_in) / time_elapsed
local out_rate = (out_octets - prev_out) / time_elapsed

print("Taxa de entrada:", in_rate, "bytes/seg")
print("Taxa de saída:", out_rate, "bytes/seg")
print("Erros de entrada:", in_errors)
print("Erros de saída:", out_errors)

Inventário de Interfaces com Walk:
-- Listar todas as interfaces com walk
local interfaces = snmp.walk("1.3.6.1.2.1.2.2.1.2", 300) -- ifDescr com cache de 5 minutos

print("=== Inventário de Interfaces ===")
for oid, ifname in pairs(interfaces) do
 -- Extrair índice da interface do OID
 local index = string.match(oid, "(%d+)$")

 -- Obter tipo e status da interface
 local iftype = snmp.get("1.3.6.1.2.1.2.2.1.3." .. index) -- ifType
 local ifstatus = snmp.get("1.3.6.1.2.1.2.2.1.8." .. index) -- ifOperStatus

 local status_text = "DOWN"
 if ifstatus == 1 then status_text = "UP" end

 print(string.format("Interface %s: %s (Tipo: %d, Status: %s)",
 index, ifname, iftype, status_text))
end

print("Total de interfaces:", snmp.count("1.3.6.1.2.1.2.2.1.2"))

Monitoramento de Uso de CPU com Múltiplas Instâncias:
-- Usar walk para obter todas as CPUs
local cpu_oids = snmp.walk("1.3.6.1.2.1.25.3.3.1.2", 30) -- hrProcessorLoad

local total_load = 0
local cpu_count = 0

for oid, load in pairs(cpu_oids) do
 cpu_count = cpu_count + 1
 total_load = total_load + load

 local cpu_index = string.match(oid, "(%d+)$")
 print(string.format("CPU %d: %d%%", cpu_index, load))
end

if cpu_count > 0 then
 local avg_load = total_load / cpu_count
 print(string.format("Média de uso de CPU: %.1f%%", avg_load))
end