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/snmp_manager/<device_name>/<source>/...
Once manager device is enabled, it will try to open UDP endpoint and start
communication with remote agent - periodical polling of OIDs configured as
polling_oids each polling_delay number of seconds. From the moment device
is enabled, until first oid is read succesfully, connection status is
considered CONNECTING. When first agent’s response is successfully
received, connection status will transfer to CONNECTED state. During
CONNECTED state, manager on each read request expects to receive response
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.
If connection was CONNECTED and then transferred to DISCONNECTED
connect_delay is not waited, but CONNECTING state starts immediately.
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 gateway
read event is generated with cause set to INTERROGATE. If new data value is
changed, new gateway read event 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 events, 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 its value is discarded.
In case received oid is 1.3.6.1.6.3.15.1.1.1 and that oid was not
requested, endpoint is closed, and state is changed to DISCONNECTED.
Gateway read event will have data/type equal to ERROR in the following
scenarios:
response is Error. data/value is set to corresponding error type.
response is empty. data/value is set to GEN_ERR.
response contains Data whose oid does not match requested oid. In case response oid is one of the following (Statistics for the User-based Security Model, RFC 3414), data/value is set to the corresponding value, otherwise is GEN_ERR:
1.3.6.1.6.3.15.1.1.2 - ‘NOT_IN_TIME_WINDOWS’
1.3.6.1.6.3.15.1.1.3 - ‘UNKNOWN_USER_NAMES’
1.3.6.1.6.3.15.1.1.4 - ‘UNKNOWN_ENGINE_IDS’
1.3.6.1.6.3.15.1.1.5 - ‘WRONG_DIGESTS’
1.3.6.1.6.3.15.1.1.6 - ‘DECRYPTION_ERRORS’
response Data is one of one of the following types: EmptyData, UnspecifiedData, NoSuchObjectData, NoSuchInstanceData, EndOfMibViewData. In these cases data/value is set to the following, respectively:
EMPTY,UNSPECIFIED,NO_SUCH_OBJECT,NO_SUCH_INSTANCE,END_OF_MIB_VIEW.
Gateway write event will have success False in the following
scenarios:
response is Error that is not of type
NO_ERROR,response does not contain Data with oid from request
response Data is one of the following types: EmptyData, UnspecifiedData, NoSuchObjectData, NoSuchInstanceData, EndOfMibViewData.
In all other cases, success is True.
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. If gateway read events are
result of polling request, session_id is null.
Gateway events¶
Events registered by gateway have event type starting with:
gateway/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. registered by the module on each status change.…/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/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/snmp_trap_listener/<device_name>/<source>/...
During device creation (after device is enabled), SNMP receiving endpoint is created. Lifetime of device is bound to created endpoint - device will not be created if endpoint initialization fails and by closing device, endpoint is also closed.
Trap listener device receives SNMP traps and informs and registers events representing their data payload. Received data is grouped based on remote device as defined by configuration. Remote device is identified with SNMP version and optional community/context. Single received data can be associated with multiple remote devices.
Gateway events¶
Events registered by gateway have event type starting with:
gateway/snmp_trap_listener/<device_name>/gateway/...
Available gateway events are:
…/data/<remote_device>/<oid>
Data notification.
Payload is defined by
hat-gateway://snmp.yaml#/$defs/events/trap_listener/gateway/data.
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:
allOf:
- oneOf:
- $ref: "hat-gateway://snmp.yaml#/$defs/managers/v1"
- $ref: "hat-gateway://snmp.yaml#/$defs/managers/v2c"
- $ref: "hat-gateway://snmp.yaml#/$defs/managers/v3"
- type: object
required:
- remote_host
- remote_port
- connect_delay
- request_timeout
- request_retry_count
- request_retry_delay
- polling_delay
- polling_oids
- string_hex_oids
properties:
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
items:
type: string
description: |
OID read during polling cycle formated as integers
separated by '.'
string_hex_oids:
type: array
items:
type: string
description: |
OID associated to string hex value formated as
integers separated by '.'
trap_listener:
type: object
required:
- local_host
- local_port
- users
- remote_devices
properties:
local_host:
type: string
description: |
Local listening hostname or IP address
local_port:
type: integer
description: |
Local listening UDP port
users:
type: array
items:
type: object
required:
- name
- authentication
- privacy
properties:
name:
type: string
authentication:
oneOf:
- type: "null"
- type: object
required:
- type
- password
properties:
type:
enum:
- MD5
- SHA
password:
type: string
privacy:
oneOf:
- type: "null"
- type: object
required:
- type
- password
properties:
type:
const: DES
password:
type: string
remote_devices:
type: array
items:
allOf:
- oneOf:
- type: object
required:
- version
- community
properties:
version:
enum:
- V1
- V2C
community:
type:
- "null"
- string
- type: object
required:
- version
- context
properties:
version:
const: V3
context:
oneOf:
- type: "null"
- type: object
required:
- engine_id
- name
properties:
engine_id:
type: string
description: |
sequence of hexadecimal
digits
name:
type: string
- type: object
required:
- name
- oids
- string_hex_oids
properties:
name:
type: string
description: |
remote device name
oids:
type: array
items:
type: string
description: |
data OID formated as integers separated
by '.'
string_hex_oids:
type: array
items:
type: string
description: |
OID associated to string hex value
formated as integers separated by '.'
managers:
v1:
type: object
required:
- version
- community
properties:
version:
const: V1
community:
type: string
v2c:
type: object
required:
- version
- community
properties:
version:
const: V2C
community:
type: string
v3:
type: object
required:
- version
- context
- user
- authentication
- privacy
properties:
version:
const: V3
context:
oneOf:
- type: "null"
- type: object
required:
- engine_id
- name
properties:
engine_id:
type: string
description: |
sequence of hexadecimal digits
name:
type: string
user:
type: string
authentication:
oneOf:
- type: "null"
- type: object
required:
- type
- password
properties:
type:
enum:
- MD5
- SHA
password:
type: string
privacy:
oneOf:
- type: "null"
- type: object
required:
- type
- password
properties:
type:
const: DES
password:
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"
trap_listener:
gateway:
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
- STRING_HEX
- 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
- NOT_IN_TIME_WINDOWS
- UNKNOWN_USER_NAMES
- UNKNOWN_ENGINE_IDS
- WRONG_DIGESTS
- DECRYPTION_ERRORS