SNMP devices#
Together with SNMP specific events, generic enable and running events are also supported.
SNMP specific events don’t contain source_timestamp.
OIDs and IP addresses are encoded as strings containing . delimited
decimal numbers.
ARBITRARY data is encoded as strings where byte is represented with
two hexadecimal lowercase characters.
Manager device#
SNMP manager device configuration is specified by
hat-gateway://snmp.yaml#/$defs/manager.
According to gateway specification, all SNMP manager device event types have prefix:
'gateway', <gateway_name>, 'snmp_manager', <device_name>, <source>, ...
Once manager device is enabled, it will try to open UDP endpoint and start
communication with remote agent. During this time, connection status is
considered CONNECTING. When first agent’s response is successfully
received, connection status will transfer to CONNECTED state. During
CONNECTED state, manager expects to receive response messages in
configured request_timeout period. If response is not received in this
period, manager will try to re-transmit request request_retry_count number
of times. If no response is received during this period, manager will
close UDP endpoint, transfer to DISCONNECTED state and wait configured
connect_delay time before trying to reestablish connection.
Manager reads remote data as a result of received read requests or based on
configured polling list. OIDs configured in polling list are read periodically
and compared to cache of previously read data. If cache doesn’t contain
previous data value, new read result is generated with cause set to
INTERROGATE. If new data value is changed, new read result is generated
with cause set to CHANGE. Connection’s transfer to DISCONNECTED state
clears data cache. All agent’s responses, which are result of system read
requests, always generate new read result events with cause set to
REQUESTED (event is registered even if received value is the same as
previously cached value).
If configured polling_oids list is empty, manager will try to periodically
read value of “0.0” OID. Result of this read is used only for connection
state detection and it’s value is discarded.
Events, representing system requests for read and write actions, contain arbitrary session_id value. This value is included in gateway events representing read and write action results.
Gateway events#
Events registered by gateway have event type starting with:
'gateway', <gateway_name>, 'snmp_manager', <device_name>, 'gateway', ...
Available gateway events are:
…, ‘status’
Connection status.
Payload is defined by
hat-gateway://snmp.yaml#/$defs/events/manager/gateway/status.…, ‘read’, <oid>
Get data result.
Payload is defined by
hat-gateway://snmp.yaml#/$defs/events/manager/gateway/read.…, ‘write’, <oid>
Set data result.
Payload is defined by
hat-gateway://snmp.yaml#/$defs/events/manager/gateway/write.
System events#
Events registered by other Hat components, which are consumed by gateway, have event type starting with:
'gateway', <gateway_name>, 'snmp_manager', <device_name>, 'system', ...
Available system events are:
…, ‘read’, <oid>
Get data request.
Payload is defined by
hat-gateway://snmp.yaml#/$defs/events/manager/system/read.…, ‘write’, <oid>
Write data request.
Payload is defined by
hat-gateway://snmp.yaml#/$defs/events/manager/system/write.
Trap listener device#
SNMP trap listener device configuration is specified by
hat-gateway://snmp.yaml#/$defs/trap_listener.
According to gateway specification, all SNMP trap listener device event types have prefix:
'gateway', <gateway_name>, 'snmp_trap_listener', <device_name>, <source>, ...
Gateway events#
Events registered by gateway have event type starting with:
'gateway', <gateway_name>, 'snmp_trap_listener', <device_name>, 'gateway', ...
Available gateway events are:
…, ‘data’, <oid>
Agent device#
…
Trap sender device#
…
Configurations and event payloads#
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "hat-gateway://snmp.yaml"
$defs:
manager:
type: object
required:
- snmp_version
- snmp_context
- remote_host
- remote_port
- connect_delay
- request_timeout
- request_retry_count
- request_retry_delay
- polling_delay
- polling_oids
properties:
snmp_version:
enum:
- V1
- V2C
- V3
snmp_context:
type: object
required:
- engine_id
- name
properties:
engine_id:
type:
- "null"
- string
description: |
Available only in case of V3 version
name:
type: string
description: |
Used as community name in case of V1 or V2C version
remote_host:
type: string
description: |
Remote hostname or IP address
remote_port:
type: integer
description: |
Remote UDP port
connect_delay:
type: number
description: |
Delay (in seconds) between two consecutive connection
establishment attempts
request_timeout:
type: number
description: |
Maximum duration (in seconds) of request/response exchange
request_retry_count:
type: integer
description: |
Number of request retries before remote data is considered
unavailable
request_retry_delay:
type: number
description: |
Delay (in seconds) between two consecutive request retries
polling_delay:
type: number
description: |
Delay (in seconds) between two consecutive polling cycles
polling_oids:
type: array
description: |
List of OIDs read during polling cycle
items:
type: string
events:
manager:
gateway:
status:
enum:
- CONNECTING
- CONNECTED
- DISCONNECTED
read:
type: object
required:
- session_id
- cause
- data
properties:
session_id:
oneOf:
- type: "null"
description: |
In case of INTERROGATE or CHANGE cause
- description: |
In case of REQUESTED cause
cause:
- INTERROGATE
- CHANGE
- REQUESTED
data:
$ref: "hat-gateway://snmp.yaml#/$defs/data"
write:
type: object
required:
- session_id
- success
properties:
success:
type: boolean
system:
read:
type: object
required:
- session_id
write:
type: object
required:
- session_id
- data
properties:
data:
$ref: "hat-gateway://snmp.yaml#/$defs/data"
data:
oneOf:
- type: object
required:
- type
- value
properties:
type:
enum:
- INTEGER
- UNSIGNED
- COUNTER
- BIG_COUNTER
- TIME_TICKS
value:
type: integer
- type: object
required:
- type
- value
properties:
type:
enum:
- STRING
- OBJECT_ID
- IP_ADDRESS
- ARBITRARY
value:
type: string
- type: object
required:
- type
- value
properties:
type:
const: ERROR
value:
enum:
- TOO_BIG
- NO_SUCH_NAME
- BAD_VALUE
- READ_ONLY
- GEN_ERR
- NO_ACCESS
- WRONG_TYPE
- WRONG_LENGTH
- WRONG_ENCODING
- WRONG_VALUE
- NO_CREATION
- INCONSISTENT_VALUE
- RESOURCE_UNAVAILABLE
- COMMIT_FAILED
- UNDO_FAILED
- AUTHORIZATION_ERROR
- NOT_WRITABLE
- INCONSISTENT_NAME
- EMPTY
- UNSPECIFIED
- NO_SUCH_OBJECT
- NO_SUCH_INSTANCE
- END_OF_MIB_VIEW