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