# Objects

Objects define the SNMP objects and attributes that may be polled by the SNMP Input.

The location of the object definition files is specified by `EF_INPUT_SNMP_OBJECT_DEFINITIONS_DIRECTORY_PATH` in the collectors configuration options. The default location is `/etc/elastiflow/snmp/objects`.

### Configuration Example

```yaml
IF-MIB::ifEntry:
  mib: IF-MIB
  object: ifEntry
  index:
    - type: Integer
      oid: .1.3.6.1.2.1.2.2.1.1
      name: netif
      syntax: InterfaceIndex
  discovery_attribute: ifDescr
  attributes:
    ifDescr:
      oid: .1.3.6.1.2.1.2.2.1.2
      tag: true
      name: netif.descr
      syntax: DisplayString
    ifType:
      oid: .1.3.6.1.2.1.2.2.1.3
      tag: true
      name: netif.type
      syntax: IANAifType
    ifSpeed:
      oid: .1.3.6.1.2.1.2.2.1.5
      name: netif.bandwidth.bw
      syntax: Gauge32
    ifPhysAddress:
      oid: .1.3.6.1.2.1.2.2.1.6
      tag: true
      name: netif.mac
      syntax: PhysAddress
    ifAdminStatus:
      oid: .1.3.6.1.2.1.2.2.1.7
      name: netif.state.admin
      syntax: EnumInteger
    ifOperStatus:
      oid: .1.3.6.1.2.1.2.2.1.8
      name: netif.state.oper
      syntax: EnumInteger
    ifInOctets:
      oid: .1.3.6.1.2.1.2.2.1.10
      name: netif.bytes.in
      syntax: Counter32
    ifInUcastPkts:
      oid: .1.3.6.1.2.1.2.2.1.11
      name: netif.packets.ucast.in
      syntax: Counter32
    ifInDiscards:
      oid: .1.3.6.1.2.1.2.2.1.13
      name: netif.packets.discard.in
      syntax: Counter32
    ifInErrors:
      oid: .1.3.6.1.2.1.2.2.1.14
      name: netif.packets.error.in
      syntax: Counter32
    ifInUnknownProtos:
      oid: .1.3.6.1.2.1.2.2.1.15
      name: netif.packets.unkproto.in
      syntax: Counter32
    ifOutOctets:
      oid: .1.3.6.1.2.1.2.2.1.16
      name: netif.bytes.out
      syntax: Counter32
    ifOutUcastPkts:
      oid: .1.3.6.1.2.1.2.2.1.17
      name: netif.packets.ucast.out
      syntax: Counter32
    ifOutDiscards:
      oid: .1.3.6.1.2.1.2.2.1.19
      name: netif.packets.discard.out
      syntax: Counter32
    ifOutErrors:
      oid: .1.3.6.1.2.1.2.2.1.20
      name: netif.packets.error.out
      syntax: Counter32
```

### Configuration Attributes

#### mib

Contains the name of the SNMP MIB where the object is defined.

EXAMPLE: `mib: IF-MIB`

#### object

Contains the name of the SNMP object which the attributes. This is usually one level up from where the attributes are defined.

EXAMPLE: `object: ifEntry`

#### index (optional)

The Object Identifier (OID) of a value provided by an agent is made of of the OID of the values definition and the ID of the index of the value within the agent. Scalar SNMP values will always have an index of `.0`. The index of values within an SNMP conceptual table is defined in the MIB by the `INDEX` clause.

This option describes the contents of the index, and how the collector will process them. The following are examples of index definitions.

:::caution An contains attributes from a conceptual table **must** include either `index` or `augments` definition. If both are omitted, the object's attributes must be only scalar values. :::

A single value `index`:

```yaml
index:
  - type: Integer
    oid: .1.3.6.1.2.1.2.2.1.1
    name: netif
    syntax: InterfaceIndex
```

A multi-value `index`:

```yaml
index:
  - type: IpAddress
    oid: .1.3.6.1.2.1.14.17.1.1
    name: ospf.lsdb.link_local.lsa.netif # ospfLocalLsdbIpAddress
    syntax: IpAddress
  - type: Integer32
    oid: .1.3.6.1.2.1.14.17.1.2
    name: ospf.lsdb.link_local.lsa.netif # ospfLocalLsdbAddressLessIf
    syntax: InterfaceIndexOrZero
  - type: Integer
    oid: .1.3.6.1.2.1.14.17.1.3
    name: ospf.lsdb.link_local.lsa.type # ospfLocalLsdbType
    syntax: EnumInteger
  - type: IpAddress
    oid: .1.3.6.1.2.1.14.17.1.4
    name: ospf.lsdb.link_local.lsa.lsid # ospfLocalLsdbLsid
    syntax: IpAddressNoSuffix
  - type: IpAddress
    oid: .1.3.6.1.2.1.14.17.1.5
    name: ospf.lsdb.link_local.lsa.router.id # ospfLocalLsdbRouterId
    syntax: IpAddressNoSuffix # RouterID
```

**type**

Defines the type of the index value. Valid values are:

* `Integer`
* `OctetString`
* `ImplicitOctetString`
* `ObjectIdentifier`
* `ImplicitObjectIdentifier`
* `Integer32`
* `IpAddress`
* `MacAddress`
* `Unsigned32`
* `Opaque`

**oid**

The OID of the index value's MIB definition.

EXAMPLE: `oid: .1.3.6.1.2.1.2.2.1.1`

**name**

The name of the field in the output record to which the value will be assigned.

**syntax**

The syntax of the value. See below for details on all supported `syntax` values.

#### augments (optional)

An object which "augments" another object shares the `index` definition of that object.

:::caution An contains attributes from a conceptual table **must** include either `index` or `augments` definition. If both are omitted, the object's attributes must be only scalar values. :::

EXAMPLE: `augments: IF-MIB::ifEntry`

#### discovery\_attribute

The attribute defined in the `attributes` section which will be inspected to discover all available indices.

#### attributes

The attributes section contains a list of SNMP MIB values to collect for this object.

**oid**

The OID of the value's MIB definition.

EXAMPLE: `oid .1.3.6.1.2.1.31.1.1.1.6`

**tag (optional)**

Specifies whether the attribute is "tag", also referred to as a "label" or "dimension" by various time-series datastores, or a metric value.

Default: `tag: false`

**name**

The name of the field in the output record to which the attribute's value will be assigned.

**syntax**

The syntax of the value. See below for details on all supported `syntax` values.

**overrides (optional)**

A common SNMP pattern is the instrumentation of both 32-bit and 64-bit variations of a value. In such scenarios it is unnecessary to collect both values. For example, when the 64-bit value is available it should be preferred, or "override" the 32-bit version.

This attribute defines the object and attribute that an attribute should override, if available.

EXAMPLE:

```yaml
overrides:
  object: IF-MIB::ifEntry
  attribute: ifOutOctets
```

**object**

The object of the attribute to be overridden.

**attribute**

The attribute of to be overridden.

**rediscover**

Defines whether the attribute can trigger a rediscovery, and how the value is evaluated to trigger the rediscovery. Valid values are:

* `OnChange` - Any change in the value compared to the previous poll.
* `OnReset` - A reduction in the value compared to the previous poll.

### Supported `syntax` Types

The `syntax` field specifies how the raw SNMP values should be interpreted by the ElastiFlow Unified SNMP Collector. Object index and attribute definitions support the follow `syntax` values.

#### SNMPv2-SMI (RFC 2578) Types

| syntax                | output type                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| Integer               | 64-bit integer                                                         |
| IntegerAsID           | 64-bit integer, which may be stored as a string/keyword                |
| Integer32             | 64-bit integer                                                         |
| UnsignedAsID          | 64-bit unsigned, which may be stored as a string/keyword               |
| Unsigned32            | 64-bit unsigned                                                        |
| Gauge32               | 64-bit unsigned                                                        |
| Counter32             | 64-bit unsigned                                                        |
| Counter64             | 64-bit unsigned                                                        |
| OctetString           | hex string                                                             |
| ObjectIdentifier      | string                                                                 |
| IpAddress             | IPv4 or IPv6 address, output with `.ip.addr` suffix added              |
| IpAddressNoSuffix     | IPv4 or IPv6 address, output without an added suffix                   |
| IpAddressAsID         | IPv4 address, output as an IP, which may be stored as a string/keyword |
| IpAddressAsUnsigned32 | IPv4 address, output as a unsigned 32-bit integer                      |
| TimeTicks             | 64-bit unsigned                                                        |
| Opaque                | hex string                                                             |

#### SNMPv2-TC (RFC 2579) Types

| syntax             | output type                                                 |
| ------------------ | ----------------------------------------------------------- |
| DisplayString      | string                                                      |
| PhysAddress        | MAC-formatted string                                        |
| MacAddress         | MAC-formatted string, output with `.addr` suffix added      |
| MacAddressNoSuffix | MAC-formatted string, output without an added suffix        |
| TruthValue         | enumerated `.value` & `.state`                              |
| AutonomousType     | string                                                      |
| InstancePointer    | string                                                      |
| VariablePointer    | string                                                      |
| RowPointer         | string                                                      |
| RowStatus          | enumerated ID & name                                        |
| TimeStamp          | duration normalized to EF\_PROCESSOR\_DURATION\_PRECISION   |
| TimeInterval       | duration normalized to EF\_PROCESSOR\_DURATION\_PRECISION   |
| DateAndTime        | timestamp normalized to EF\_PROCESSOR\_TIMESTAMP\_PRECISION |
| StorageType        | enumerated ID & name                                        |
| TDomain            | string                                                      |
| TAddress           | hex string                                                  |

#### FLOAT-TC-MIB (RFC 6340) Types

| syntax  | output type  |
| ------- | ------------ |
| Float32 | 64-bit float |
| Float64 | 64-bit float |

#### HCNUM-TC (RFC 2856) Types

| syntax              | output type     |
| ------------------- | --------------- |
| CounterBasedGauge64 | 64-bit unsigned |
| ZeroBasedCounter64  | 64-bit unsigned |

#### Common MIB-defined Types

| syntax               | output type                       |
| -------------------- | --------------------------------- |
| IanaL4Proto          | enumerated `.id` & `.name`        |
| IanaSafi             | enumerated `.id` & `.name`        |
| IANAifType           | enumerated `.id` & `.name`        |
| InterfaceIndex       | output with `.index` suffix added |
| InterfaceIndexOrZero | output with `.index` suffix added |
| InetAddressType      | enumerated `.id` & `.name`        |
| InetVersion          | enumerated `.id` & `.name`        |

#### Enumerated Types

| syntax                      | output type                                     |
| --------------------------- | ----------------------------------------------- |
| EnumBitmap                  | enumerated `.bits` & `.tags` - see Enumerations |
| EnumInteger                 | enumerated `.id` & `.name` - see Enumerations   |
| EnumIntegerKeepID           | enumerated `.id` & `.name` - see Enumerations   |
| EnumObjectIdentifier        | enumerated `.oid` & `.name` - see Enumerations  |
| EnumObjectIdentifierKeepOID | enumerated `.oid` & `.name` - see Enumerations  |

#### Unit Types

Unit types can be defined for any attribute with an underlying type of `Integer`, `Integer32`, `Unsigned32`, `Gauge32`, `Counter32`, `Counter64`, `Float32` or `Float64`.

**Bandwidth Types**

Bandwidth types are normalized to **bits/sec** and output as a **64-bit unsigned** value.

| syntax          | description                      |
| --------------- | -------------------------------- |
| BandwidthBits   | bits                             |
| BandwidthKBits  | kilobits (`1000` bits)           |
| BandwidthMBits  | megabits (`1000000` bits)        |
| BandwidthGBits  | gigabits (`1000000000` bits)     |
| BandwidthTBits  | terabits (`1000000000000` bits)  |
| BandwidthBytes  | bytes (`8` bits)                 |
| BandwidthKBytes | kilobytes (`8000` bits)          |
| BandwidthMBytes | megabytes (`8000000` bits)       |
| BandwidthGBytes | gigabytes (`8000000000` bits)    |
| BandwidthTBytes | terabytes (`8000000000000` bits) |

**Byte Types**

Byte types are normalized to **bytes** and output as a **64-bit unsigned** value.

| syntax   | description                       |
| -------- | --------------------------------- |
| BytesB   | bytes                             |
| BytesB4  | 4-byte units                      |
| BytesKB  | kilobytes (`1000` bytes)          |
| BytesMB  | megabytes (`1000000` bytes)       |
| BytesGB  | gigabytes (`1000000000` bytes)    |
| BytesTB  | terabytes (`1000000000000` bytes) |
| BytesKiB | kibibytes (`1024` bytes)          |
| BytesMiB | mebibytes (`1048576` bytes)       |
| BytesGiB | gibibytes (`1073741824` bytes)    |
| BytesTiB | tibibytes (`1099511627776` bytes) |

**Decibel Types**

Decibel types are normalized to **decibels** and output as a **64-bit float** value.

| syntax  | description |
| ------- | ----------- |
| Decibel | decibels    |

**Signal Level Types**

Signal Level types are normalized to **dBm** and output as a **64-bit float** value.

| syntax         | description       |
| -------------- | ----------------- |
| SignalDBm      | dBm               |
| SignalDeciDBm  | 1/10th of a dBm   |
| SignalCentiDBm | 1/100th of a dBm  |
| SignalMilliDBm | 1/1000th of a dBm |

**Current Types**

Current types are normalized to **amps** and output as a **64-bit float** value.

| syntax          | description       |
| --------------- | ----------------- |
| CurrentKiloAmp  | kiloamps          |
| CurrentAmp      | amps              |
| CurrentDeciAmp  | 1/10th of an amp  |
| CurrentCentiAmp | 1/100th of an amp |
| CurrentMilliAmp | milliamps         |
| CurrentMicroAmp | microamps         |
| CurrentNanoAmp  | nanoamps          |

**Energy Types**

Energy types are normalized to **joules** and output as a **64-bit float** value.

| syntax           | description        |
| ---------------- | ------------------ |
| EnergyGigaJoule  | gigajoules         |
| EnergyMegaJoule  | megajoules         |
| EnergyKiloJoule  | kilojoules         |
| EnergyJoule      | joules             |
| EnergyDeciJoule  | 1/10th of a joule  |
| EnergyCentiJoule | 1/100th of a joule |
| EnergyMilliJoule | millijoules        |
| EnergyMicroJoule | microjoules        |
| EnergyNanoJoule  | nanojoules         |

**Timestamp Types**

Timestamp types are normalized to **a quantity of time units since epoch**, as specified by EF\_PROCESSOR\_TIMESTAMP\_PRECISION, and output as a **64-bit unsigned** value.

| syntax        | description                      |
| ------------- | -------------------------------- |
| EpochSec      | seconds since epoch              |
| EpochDeciSec  | 1/10ths of a second since epoch  |
| EpochCentiSec | 1/100ths of a second since epoch |
| EpochMilliSec | milliseconds since epoch         |
| EpochMicroSec | microseconds since epoch         |
| EpochNanoSec  | nanoseconds since epoch          |

**Frequency Types**

Frequency types are normalized to **hertz** and output as a **64-bit float** value.

| syntax      | description |
| ----------- | ----------- |
| FreqGHz     | gigahertz   |
| FreqMHz     | megahertz   |
| FreqKHz     | kilohertz   |
| FreqHz      | hertz       |
| FreqDeciHz  | decihertz   |
| FreqCentiHz | centihertz  |
| FreqMilliHz | millihertz  |

**Length Types**

Length types are normalized to **meters** and output as a **64-bit float** value.

| syntax           | description |
| ---------------- | ----------- |
| LengthKiloMeter  | kilometers  |
| LengthMeter      | meters      |
| LengthDeciMeter  | decimeters  |
| LengthCentiMeter | centimeters |
| LengthMilliMeter | millimeters |
| LengthMicroMeter | micrometers |
| LengthNanoMeter  | nanometers  |

**Operation Duration Types**

Operation Duration types are normalized to **nanoseconds** and output as a **64-bit float** value.

| syntax                 | description          |
| ---------------------- | -------------------- |
| OpTicksSec             | seconds              |
| OpTicksDeciSec         | 1/10ths of a second  |
| OpTicksCentiSec        | 1/100ths of a second |
| OpTicksMilliSec        | milliseconds         |
| OpTicksHundredMicroSec | 100 microseconds     |
| OpTicksTenMicroSec     | 10 microseconds      |
| OpTicksMicroSec        | microseconds         |
| OpTicksHundredNanoSec  | 100 nanoseconds      |
| OpTicksTenNanoSec      | 10 nanoseconds       |
| OpTicksNanoSec         | nanoseconds          |
| OpTicksHundredPicoSec  | 100 picoseconds      |
| OpTicksTenPicoSec      | 10 picoseconds       |
| OpTicksPicoSec         | picoseconds          |

**Percentage Types**

Percentage types are normalized to **either a 0-1 or 0-100 based percentage**, as specified by EF\_PROCESSOR\_PERCENT\_NORM, and output as a **64-bit float** value.

| syntax          | description                                      |
| --------------- | ------------------------------------------------ |
| Percent1        | 0-1 based percentage                             |
| PercentDeci1    | 0-1 based percentage in 1/10ths of a percent     |
| PercentCenti1   | 0-1 based percentage in 1/100ths of a percent    |
| PercentMilli1   | 0-1 based percentage in 1/1000ths of a percent   |
| Percent100      | 0-100 based percentage                           |
| PercentDeci100  | 0-100 based percentage in 1/10ths of a percent   |
| PercentCenti100 | 0-100 based percentage in 1/100ths of a percent  |
| PercentMilli100 | 0-100 based percentage in 1/1000ths of a percent |

**Power Types**

Power types are normalized to **watts** and output as a **64-bit float** value.

| syntax         | description |
| -------------- | ----------- |
| PowerGigaWatt  | gigawatts   |
| PowerMegaWatt  | megawatts   |
| PowerKiloWatt  | kilowatts   |
| PowerWatt      | watts       |
| PowerDeciWatt  | deciwatts   |
| PowerCentiWatt | centiwatts  |
| PowerMilliWatt | milliwatts  |
| PowerMicroWatt | microwatts  |
| PowerNanoWatt  | nanowatts   |

**Rate Types**

Rate types are normalized to **quantity/sec** and output as a **64-bit float** value.

| syntax       | description                        |
| ------------ | ---------------------------------- |
| RateMin      | a quantity per minute              |
| RateSec      | a quantity per second              |
| RateDeciSec  | a quantity per 1/10th of a second  |
| RateCentiSec | a quantity per 1/100th of a second |
| RateMilliSec | a quantity per millisecond         |
| RateMicroSec | a quantity per microsecond         |
| RateNanoSec  | a quantity per nanosecond          |

**Temperature Types**

Temperature types are normalized to **degrees celsius** and output as a **64-bit float** value.

| syntax            | description              |
| ----------------- | ------------------------ |
| TemperatureC      | degrees celsius          |
| TemperatureDeciC  | 1/10th degrees celsius   |
| TemperatureCentiC | 1/100th degrees celsius  |
| TemperatureMilliC | 1/1000th degrees celsius |

**Duration Types**

Duration types are normalized to **a quantity of time units**, as specified by EF\_PROCESSOR\_DURATION\_PRECISION, and output as a **64-bit unsigned** value.

| syntax        | description          |
| ------------- | -------------------- |
| TicksMin      | minutes              |
| TicksSec      | seconds              |
| TicksDeciSec  | 1/10ths of a second  |
| TicksCentiSec | 1/100ths of a second |
| TicksMilliSec | milliseconds         |
| TicksMicroSec | microseconds         |
| TicksNanoSec  | nanoseconds          |

**Voltage Types**

Voltage types are normalized to **volts** and output as a **64-bit float** value.

| syntax           | description        |
| ---------------- | ------------------ |
| VoltageKiloVolt  | kilovolts          |
| VoltageVolt      | volts              |
| VoltageDeciVolt  | 1/10ths of a volt  |
| VoltageCentiVolt | 1/100ths of a volt |
| VoltageMilliVolt | millivolts         |
| VoltageMicroVolt | microvolts         |
| VoltageNanoVolt  | nanovolts          |

**Wavelength Types**

Wavelength types are normalized to **nanometers** and output as a **64-bit float** value.

| syntax               | description |
| -------------------- | ----------- |
| WavelengthKiloMeter  | kilometers  |
| WavelengthMeter      | meters      |
| WavelengthDeciMeter  | decimeters  |
| WavelengthCentiMeter | centimeters |
| WavelengthMilliMeter | millimeters |
| WavelengthMicroMeter | micrometers |
| WavelengthNanoMeter  | meters      |