Skip to content

Commit 67a5b4a

Browse files
hellthellt
committed
use full examples instead of excerpts
1 parent ed52856 commit 67a5b4a

File tree

1 file changed

+51
-137
lines changed

1 file changed

+51
-137
lines changed

‎docs/snmp/snmp_framework.md

Lines changed: 51 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -38,114 +38,12 @@ trap-definitions:
3838
3939
The table definition YAML file describes the framework components used to define a particular MIB table. Take the `if_mib.yaml` file for example, it maps interface-related data to standard MIB tables such as `ifTable`, `ifXTable`, and `ifStackTable`.
4040

41-
You can list the contents of this file with `cat /opt/srlinux/snmp/scripts/if_mib.yaml` command and at the end of this section, and to help us document the fields of the table definition file let us also provide a short snippet from this file:
42-
43-
```{.yaml .code-scroll-lg}
44-
paths:
45-
- /interface/
46-
- /interface/ethernet
47-
- /interface/lag
48-
python-script: if_mib.py
49-
enabled: true
50-
tables:
51-
- name: ifTable
52-
enabled: true
53-
oid: 1.3.6.1.2.1.2.2
54-
indexes:
55-
- name: ifIndex
56-
oid: 1.3.6.1.2.1.2.2.1.1
57-
syntax: integer
58-
columns:
59-
- name: ifIndex
60-
oid: 1.3.6.1.2.1.2.2.1.1
61-
syntax: integer
62-
- name: ifDescr
63-
oid: 1.3.6.1.2.1.2.2.1.2
64-
syntax: octet string
65-
- name: ifXTable
66-
enabled: true
67-
oid: 1.3.6.1.2.1.31.1.1
68-
augment: ifTable
69-
columns:
70-
- name: ifName
71-
oid: 1.3.6.1.2.1.31.1.1.1.1
72-
syntax: octet string
73-
- name: ifInMulticastPkts
74-
oid: 1.3.6.1.2.1.31.1.1.1.2
75-
syntax: counter32
76-
- name: ifStackTable
77-
enabled: true
78-
oid: 1.3.6.1.2.1.31.1.2
79-
indexes:
80-
- name: ifStackHigherLayer
81-
oid: 1.3.6.1.2.1.31.1.2.1.1
82-
syntax: integer
83-
- name: ifStackLowerLayer
84-
oid: 1.3.6.1.2.1.31.1.2.1.2
85-
syntax: integer
86-
columns:
87-
- name: ifStackStatus
88-
oid: 1.3.6.1.2.1.31.1.2.1.3
89-
syntax: integer
90-
scalars:
91-
- name: ifNumber
92-
enabled: true
93-
oid: 1.3.6.1.2.1.2.1
94-
syntax: integer
95-
- name: ifTableLastChange
96-
enabled: true
97-
oid: 1.3.6.1.2.1.31.1.5
98-
syntax: timeticks
99-
```
100-
101-
The table definition file has the following important top level fields:
102-
103-
* `paths`: Specifies the gNMI paths for retrieving data.
104-
* `python-script`: References the uPython script used for data conversion.
105-
* `tables`: Lists MIB tables, their structure, and their OIDs.
106-
* `scalars`: Defines scalar OIDs.
107-
108-
Under the `tables` key you find the list of MIB table definitions, where each table has the following structure:
109-
110-
* `name`: Specifies the name of the SNMP table. This is used for identification and reference in the SNMP configuration.
111-
* `enabled`: Determines whether the table is active (true) or inactive (false).
112-
* `oid`: The base Object Identifier (OID) for the table. All rows and columns in the table are extensions of this base OID.
113-
* `augment`: **TODO: add description**
114-
* `indexes`: Indexes uniquely identify rows in the table. Each index maps a specific OID to a value that differentiates rows. A list of column definitions that serve as unique identifiers for rows.
115-
* `name`: The name of the index column.
116-
* `oid`: The OID for the index.
117-
* `syntax`: The data type of the index value.
118-
* `columns`: Columns represent attributes or properties for each row in the table. Each column is defined with an OID and a data type.
119-
* `name`: The name of the column.
120-
* `oid`: The OID for the column.
121-
* `syntax`: The data type of the column's value.
122-
* `binary`: (optional) Indicates if the value is base64-encoded.
123-
* `enabled`: (optional) Enables or disables the column.
124-
125-
The `syntax` field in SNMP table and scalar definitions specifies the data type of the OID value. Each data type maps to a specific ASN.1 type, defining how the data is represented and transmitted in SNMP operations. Below is a detailed explanation of the supported data types.
126-
127-
* `octet string`: Represents a sequence of octets (bytes). Commonly used for textual information (e.g., names, descriptions) or raw binary data. E.g: `ifDescr`.
128-
* `integer / integer32`: Represents a signed 32-bit integer. Used for numeric attributes like counters, states, or enumerations. E.g: `ifType`, `ifAdminStatus`, `ifOperStatus`.
129-
* `unsigned / unsigned32`: Represents an unsigned 32-bit integer. E.g: values that should not be negative like counts or identifiers.
130-
* `counter / counter32`: Represents a counter that increments over time and wraps back to 0 when it exceeds the maximum value (4,294,967,295). E.g: `ifInOctets`, `ifOutOctets`.
131-
* `counter64`: Represents a 64-bit counter for high-capacity devices or metrics with large values. E.g: `ifHCInOctets`, `ifHCOutOctets`.
132-
* `gauge / gauge32`: Represents a non-negative integer that can increase or decrease but cannot wrap. E.g `ifSpeed`.
133-
* `timeticks`: Represents time in hundredths of a second since a device was last initialized or restarted. E.g: `ifLastChange`.
134-
* `ipaddress`: Represents an IPv4 address as a 32-bit value. Stored and transmitted in network byte order (big-endian).
135-
* `object identifier`: Represents an OID as a series of numbers identifying objects or properties in the SNMP tree.
136-
* `bits`: Represents a sequence of bits, often used to define flags or multiple binary states.
41+
You can list the contents of this file with `cat /opt/srlinux/snmp/scripts/if_mib.yaml` command and we provide it here for reference:
13742

13843
/// details | `if_mib.yaml` definition file
13944
type: subtle-note
14045

14146
```yaml
142-
###########################################################################
143-
# Description:
144-
#
145-
# Copyright (c) 2024 Nokia
146-
###########################################################################
147-
# yaml-language-server: $schema=../table_definition_schema.json
148-
14947
#- This is the mapping for interfaces and subinterfaces. It defines MIB tables ifTable, ifXTable and ifStackTable.
15048
paths:
15149
- /interface/
@@ -323,6 +221,46 @@ scalars:
323221

324222
///
325223

224+
The table definition file has the following important top level fields:
225+
226+
* `paths`: Specifies the gNMI paths for retrieving data.
227+
* `python-script`: References the uPython script used for data conversion.
228+
* `tables`: Lists MIB tables, their structure, and their OIDs.
229+
* `scalars`: Defines scalar OIDs.
230+
231+
Under the `tables` key you find the list of MIB table definitions, where each table has the following structure:
232+
233+
* `name`: Specifies the name of the SNMP table. This is used for identification and reference in the SNMP configuration.
234+
* `enabled`: Determines whether the table is active (true) or inactive (false).
235+
* `oid`: The base Object Identifier (OID) for the table. All rows and columns in the table are extensions of this base OID.
236+
* `indexes`: Indexes uniquely identify rows in the table. Each index maps a specific OID to a value that differentiates rows. A list of column definitions that serve as unique identifiers for rows.
237+
* `name`: The name of the index column.
238+
* `oid`: The OID for the index.
239+
* `syntax`: The data type of the index value.
240+
* `columns`: Columns represent attributes or properties for each row in the table. Each column is defined with an OID and a data type.
241+
* `name`: The name of the column.
242+
* `oid`: The OID for the column.
243+
* `syntax`: The data type of the column's value.
244+
* `binary`: (optional) Indicates if the value is base64-encoded.
245+
* `enabled`: (optional) Enables or disables the column.
246+
247+
The `syntax` field in SNMP table and scalar definitions specifies the data type of the OID value. Each data type maps to a specific ASN.1 type, defining how the data is represented and transmitted in SNMP operations. Below is a detailed explanation of the supported data types.
248+
249+
/// details | Data Types
250+
type: subtle-note
251+
252+
* `octet string`: Represents a sequence of octets (bytes). Commonly used for textual information (e.g., names, descriptions) or raw binary data. E.g: `ifDescr`.
253+
* `integer / integer32`: Represents a signed 32-bit integer. Used for numeric attributes like counters, states, or enumerations. E.g: `ifType`, `ifAdminStatus`, `ifOperStatus`.
254+
* `unsigned / unsigned32`: Represents an unsigned 32-bit integer. E.g: values that should not be negative like counts or identifiers.
255+
* `counter / counter32`: Represents a counter that increments over time and wraps back to 0 when it exceeds the maximum value (4,294,967,295). E.g: `ifInOctets`, `ifOutOctets`.
256+
* `counter64`: Represents a 64-bit counter for high-capacity devices or metrics with large values. E.g: `ifHCInOctets`, `ifHCOutOctets`.
257+
* `gauge / gauge32`: Represents a non-negative integer that can increase or decrease but cannot wrap. E.g `ifSpeed`.
258+
* `timeticks`: Represents time in hundredths of a second since a device was last initialized or restarted. E.g: `ifLastChange`.
259+
* `ipaddress`: Represents an IPv4 address as a 32-bit value. Stored and transmitted in network byte order (big-endian).
260+
* `object identifier`: Represents an OID as a series of numbers identifying objects or properties in the SNMP tree.
261+
* `bits`: Represents a sequence of bits, often used to define flags or multiple binary states.
262+
///
263+
326264
## Creating Custom MIBs
327265

328266
Users can create custom MIB definitions following these steps:
@@ -333,7 +271,9 @@ Users can create custom MIB definitions following these steps:
333271

334272
### Input JSON Format
335273

336-
Recall, that SNMP framework is powered by the underlying SR Linux's gNMI infrastructure. The `paths` you define in the table mapping file will retrieve the data that the conversion script will work on to create the SNMP MIB tables.
274+
Recall, that SNMP framework is powered by the underlying SR Linux's gNMI infrastructure. The `paths` you define in the table mapping file will retrieve the data that the conversion script will work on to create the SNMP MIB tables.
275+
276+
A thing to note is that the `paths` you define in the mapping file are non-recursive; this means that the returned data will be limited to the immediate children of the path you specify. To recursively retrieve data from a path, add `...` to the end of the path, e.g. `/interface/ethernet/...`.
337277

338278
The uPython script receives data in JSON format, including global SNMP information and the gNMI query results. Here is an example of a payload the `if_mib.py` script receives.
339279

@@ -510,39 +450,7 @@ Traps are defined with the mapping files that look similar to the MIB ones, but
510450

511451
### Trap definitions
512452

513-
The trap definition YAML file has exactly the same top level elements as the table definition file but instead of `tables` the file contains `traps` top-level key. To help you map the terms with the actual contents, lets have a look at the excerpt of the `/opt/srlinux/snmp/scripts/rfc3418_traps.yaml` that defines the traps as per RFC 3418:
514-
515-
```yaml
516-
python-script: rfc3418_traps.py
517-
enabled: true
518-
traps:
519-
- name: linkDown
520-
enabled: true
521-
oid: 1.3.6.1.6.3.1.1.5.3
522-
triggers:
523-
- /interface/oper-state
524-
- /interface/subinterface/oper-state
525-
context:
526-
- /interface
527-
- /interface/subinterface
528-
data:
529-
- indexes:
530-
- name: ifIndex
531-
syntax: integer
532-
objects:
533-
- name: ifIndex
534-
oid: 1.3.6.1.2.1.2.2.1.1
535-
syntax: integer
536-
- name: ifAdminStatus
537-
oid: 1.3.6.1.2.1.2.2.1.7
538-
syntax: integer
539-
```
540-
541-
Besides the common `name`, `enabled` and `oid` fields, the `traps` object has the following fields:
542-
543-
* `triggers`: Specifies paths that trigger the trap.
544-
* `context`: Additional paths to fetch data for the trap.
545-
* `data`: Defines variable bindings included in the trap.
453+
The trap definition YAML file has exactly the same top level elements as the table definition file but instead of `tables` the file contains `traps` top-level key. Here is the contents of the `/opt/srlinux/snmp/scripts/rfc3418_traps.yaml` mapping file that defines the traps as per RFC 3418:
546454

547455
/// details | `rfc3418_traps.yaml` definition file
548456
type: subtle-note
@@ -628,6 +536,12 @@ traps:
628536

629537
///
630538

539+
Besides the common `name`, `enabled` and `oid` fields, the `traps` object has the following fields:
540+
541+
* `triggers`: Specifies paths that trigger the trap.
542+
* `context`: Additional paths to fetch data for the trap.
543+
* `data`: Defines variable bindings included in the trap.
544+
631545
## Creating Custom Traps
632546

633547
To define custom traps:

0 commit comments

Comments
 (0)