WeOS
5.29.0

# Alarm

## Introduction

Alarms can be used in order to specify specific actions to take when a particular event occurs in the system.

## Overview

    Alarm Triggers <----------------------> Alarm Actions
          ^                                       ^
          |                                       |
          |                                       |
          v                                       v
    Alarm Sources                           Alarm Targets

Figure 1: The image describes the relations between the different aspects that together constitute the alarm handling functionality in the system. Alarm triggers monitor the state of the provided source and defines conditions that should invoke an associated alarm action. The invoked alarm action specifies what alarm target(s) to use in order to notify the operator.

The alarm handling functionality in the system makes use of the following terminology:

- Alarm Sources: An alarm source is an object being monitored by an alarm trigger. This could be, for instance, the link status (up/down) of an Ethernet port or the temperature value of a temperature sensor. Alarm sources are described further in a section below.

- Alarm Triggers: An alarm trigger will monitor a provided alarm source and define the conditions for when specific alarm events occur, in other words, when the trigger becomes active (alarm situation) or inactive (normal operation).

- Alarm Actions and Alarm Targets: When an alarm event occurs, the operator can be informed in a number of ways. This is defined by a specific alarm action that is associated with any give alarm trigger. The alarm action in turn specify one or more alarm targets that will be used to notify the operator. As an example this could be SNMP traps, logging, or a front panel status LED. Alarm actions and targets are described in more detail below.

### Alarm Triggers and Alarm Sources

The alarm trigger defines rules for when a monitored source should generate an alarm event. The alarm trigger also needs to specify an alarm action to invoke when an alarm event occurs.

The system supports the following alarm sources to be associated with any given alarm trigger:

- Link Alarm: It is possible to configure link alarm triggers to react when the status of a link changes (goes up or down). A link alarm trigger can be associated with one or more Ethernet ports, and will be set to active when any of the associated ports matches the alarm condition (link up or down).

- Temperature: Temperature alarm triggers can be configured to react when the temperature rises above (or falls below) some defined threshold.

- Power: A power trigger can monitor one or more power feed sensors. Most WeOS products have two power feeds (single power supply), with a sensor for each power feed. Typically a single power trigger is used to monitor both power feed sensors.

- Digital-In: Alarms can be triggered depending on the presence of input voltage/current on the Digital-In pins of the Digital I/O connector.

- Ping: A connectivity checker, sends an ICMP ping in a configurable interval.

- HW-Failure: Hardware alarms triggers notifies that the unit has detected a hardware failure (typically if an unsupported SFP is inserted).

- RING: The RING status trigger will react when an ring is open or closed (intact). Used for FRNT and MRP ring status.

- PoE Power Usage: On units supporting Power Over Ethernet (PoE), alarms can be triggered when the total power usage raises above (or falls below) a configured threshold.

- Media: On units supporting external media (USB or SDcard) alarms can be triggered if the external device is available or unavailable.

- Media-threshold: On units supporting external media (USB or SDcard) alarms can be triggered if the used space on the media exceeds the configured threshold.

#### Alarm thresholds

For the trigger to know when an alarm event has occurred, threshold values for the monitored alarm sources must be configured.

Alarm sources which are ’binary’ to their nature (link up/down, power up/down, digital-in high/low, used space above / below etc.) have thresholds defined implicitly.

For sources which can take values in a wider range (temperature, PoE usage, etc) the alarm thresholds should be configured. Two thresholds are used, a rising threshold and a falling threshold. Alarm events will be generated when reaching the rising threshold on the way up, and the falling threshold on the way down.

However, once a rising alarm event has occurred, a new rising alarm event cannot be generated (for that alarm source) before the value has fallen down to the falling threshold (and vice versa). Thus, the use of separate rising and falling thresholds creates a hysteresis mechanism, which avoids generating multiple alarm events when a monitored value fluctuates around the alarm threshold.

Additional details on threshold settings and properties:

- The rising threshold cannot be set lower than the falling threshold.

- It is possible to use the same value for the rising and falling thresholds.

- Rising alarm events occur if the current sample value is equal or above the rising threshold, and the previously sampled value was below the rising threshold. A rising alarm event will also occur if the first sampled value is equal or above this threshold, and the condition variable is configured as rising (or any of its equivalents: high or up).

- Falling alarm events occur if the current sample value is equal or below the falling threshold, and the previously sampled value was above the falling threshold. A falling alarm event will also occur if the first sampled value is equal or below this threshold, and the condition variable is configured as falling (or any of its equivalents: low or down).

### Alarm Actions and Alarm Targets

All alarm actions in the system needs to be associated with one or more alarm targets, these dictate how the activated alarm will be presented to the operator:

- LED: here are front panel LEDs which can indicate status of specific ports or protocols. There is also a general status LED, which shows a green light when the unit is operating ‘OK’, but shows a red light as soon as any of the associated alarm triggers becomes active. Thus, the ’ON’ LED provides a summary alarm function.

- Log: Log status change to syslog.

- SNMP: Alarms can be configured to generate SNMP traps. Similiar to the ‘ON’ LED, a summary alarm trap can be enabled to send a trap with a warning OID when there’s any active alarm and send a trap with an OK OID if all alarms are inactive.

- Digout: On units equipped with a Digital I/O contact, the status relay pins (Digital-Out) can be used as an alarm target. Similar to the ‘ON’ LED, the status relay provides a summary alarm function, where the state of the ‘gate’ (closed/open) depends if the switch is operating ‘OK’, or if there is an issue (any alarm trigger active or when the unit has no power). The product may have multiple status relay pinouts, as described in the product user guide. These are referred to as normally closed (NC) or normally open (NO), where the word normally refers to the behaviour when a unit has no power (rather than if it operating OK nor not).

  - Normally Closed (NC): The NC gate will be closed when the unit is unpowered, pre-operational (booting), or when one or more alarms are active. The NC gate will be open when the unit is operational and no alarm is active.

  - Normally Open (NO): The NO gate will be open when the unit is unpowered, pre-operational (booting), or when one or more alarms are active. The NO gate will be closed when the unit is operational and no alarm is active.

- Port: Control the admin status of a port.

- Iface: Control the admin status of an interface.

## Configuration

The alarm settings can be found at the top level in the configuration context.

    example:/#> configure
    example:/config/#> alarm
    example:/config/alarm/#>

`[no] action [INDEX]`

  Create, update or remove an alarm action (profile). Use `action INDEX` to enter the Alarm Action Configuration context and create a new or update an existing action.

  Note

  Will enter a sub-context. Information on this context can be found in a section below.

  no
    Remove the specified action.
  INDEX
    Numerical index value of the action to access, create, or remove.
`[no] trigger [INDEX] [TYPE]`

  Create, update or remove an alarm trigger configuration.

  Note

  Will enter a sub-context. Information on this context can be found in a section below.

  no
    Remove the specified trigger.
  INDEX
    Numerical index value of the trigger to access, create, or remove.
  TYPE
    Type of trigger to create. Specified in the sections above. The available trigger types can also be seen with the command `show types`.
`[no] types`

  Show available trigger types.

  no
    Not applicable for this command.
`[no] summary`

  Summary alarm trap will be sent through SNMP.

  no
    Will disable summary alarm trap.

### Trigger Configuration

Trigger configuration is accessed from the top level of the alarm context:

    example:/config/alarm/#> trigger TYPE
    example:/config/alarm/trigger-1/#>

Where TYPE is the type of trigger that should be created. The types are described above when talking about Alarm Sources. The available types can also be seen with the types command in the cli:

    example:/config/alarm/#> types
    link-alarm
    temperature
    power
    digin
    ping
    ring
    poe
    media
    media-threshold

Note

Depending on the type of trigger selected, additional configuration options may appear in the Trigger configuration context.

#### Common Settings

`[no] enable`

  Enable or disable the trigger.

  no
    Disable the trigger.
`[no] action [INDEX]`

  Specify the action (profile) to be invoked when this trigger detects an alarm event.

  Default: Index 1 (default action).

  no
    Disable the mapping to an alarm action.
  INDEX
    Index of a specific action to associate with the trigger.
`[no] condition [high|low] | [unavailable|available]`

  Define whether the `high | unavailable` or `low | available` trigger state should be considered the alarm state, while the other is considered the normal state.

  Note

  Some triggers, such as power triggers, have a static (predefined) alarm condition setting. (Power triggers have condition set to low). For other triggers, the alarm condition setting is configurable.

  Default: Differs between different trigger types.

  no
    Reset option to default.
`[no] severity [LEVEL] | [active <LEVEL>] [inactive <LEVEL>]`

  Specify the severity level of active and inactive alarm events detected by this trigger.

  Active and inactive severity levels can be configured together or independently.

  Default: `active` to `warning` and `inactive` to `notice`.

  no
    Set severity to level `none`. Alarm events with severity `none` will not cause SNMP traps to be sent or events to be logged, however, such events can still affect the status relay (digital-out) and ON LED targets.
  LEVEL
    The levels use standard syslog levels: - `none` : No severity. - `debug` : Debug-level message. - `info` : Informational message. - `notice` : Normal but significant condition. - `warning`: Warning condition. - `err` : Error condition. - `crit` : Critical condition. - `alert` : Immediate action required. - `emerg` : System is unusable.

Depending on the type of alarm trigger, the way to specify the alarm source will differ. For example, for a link-alarm trigger, the associated port(s) must be defined.

`[no] threshold <NUM> | [rising <NUM>] [falling <NUM>] [percent|KB|MB|GB]`

  (For triggers with non-binary values for alarm source, such as temperature or PoE power utilisation triggers.) Two thresholds are used; a rising threshold and a falling threshold. Alarm events will be generated when reaching the rising threshold on the way up, and the falling threshold on the way down.

  no
    Reset thresholds to default.

  Threshold units: - `threshold <NUM> [percent]` — Set the threshold as a percentage of total space. - `threshold <NUM> [KB|MB|GB]` — Set the threshold in bytes.

#### Link alarm

`[no] port <PORT|PORTS>`

  (For ‘link-alarm’ trigger) Set which port(s) to trigger alarm on.

  The alarm will be set to active if any of the specified ports are triggered by the condition (link up or down).

  no
    Remove port(s).

    example:/config/alarm/#> trigger link-alarm
    example:/config/alarm/trigger-1/#> port eth2
    example:/config/alarm/trigger-1/#> show
    ID              : 1
    Type            : link-alarm
    Status          : Enabled
    Port            : eth2
    Severity        : active warning, inactive notice
    Condition       : low
    Action          : 1
    example:/config/alarm/trigger-1/#>

#### Temperature power or digin

`[no] sensor <NUM>`

  (For ‘temperature’, ‘power’ and ‘digin’ triggers) Set which sensor to trigger alarm on.

  no
    Remove sensor(s).

#### Ring Trigger

`[no] protocol <frnt|mrp|hsr|prp>`

  (For ‘ring’ triggers) Set which ring protocol to trigger alarm on. Used with ‘ring-id’ setting to define the ring protocol and instance. Default: FRNT

  no
    Reset protocol to default.
`[no] ring-id <NUM>`

  (For ‘ring’ triggers) Set which ring-id to trigger alarm on. Used with ‘protocol’ setting to define the ring protocol and ID. For FRNTv0 rings, use ring-id ‘0’ (zero).

  no
    Remove ring-id.

#### Ping Settings

`[no] peer <FQDN|IPADDR>`

  Specify the name/ address of the target used to ping

  no
    Remove the configured peer.
`[no] outbound <Interface|IPADDR>`

  Specify the interface or IP address to use as the source for outbound traffic.

  no
    Reset the source to the default gateway for the peer

Note

During testing, it was observed that when there is no clear route to the peer, the ping command works more reliably if the source address is specified as an explicit IP address rather than using the interface name.

`interval <SEC>`
  Set the frequency (in seconds) between ping samples. Default: 10
`number <NUM>`
  Set the number of packets to send/receive before evaluating the alarm condition. Default: 3
`initial-state <ok|warning>`
  Set the initial alarm state for the trigger.

#### PoE Trigger

`sensor <NUM>`
  Specify which PoE sensor(s) to monitor.
`threshold <NUM> | [rising <NUM>] [falling <NUM>] [percent|KB|MB|GB]`
  Set the power usage threshold for alarm activation.

#### Media Trigger

`media-name <NAME>`
  Specify the name of the external media (USB/SD card) to monitor.
`condition <available|unavailable>`
  Set the alarm condition based on media availability.
`interval <SEC>`
  Set the frequency between samples. Default: 10

#### Media-Threshold Trigger

`media-name <NAME>`
  Specify the name of the external media to monitor.
`threshold <NUM> [percent|KB|MB|GB]`
  Set the used space threshold for alarm activation. If used space exceeds the threshold, an alarm will be triggered. - `threshold <NUM> [percent]` — Set the threshold as a percentage of total space. - `threshold <NUM> [KB|MB|GB]` — Set the threshold in bytes.
`interval <SEC>`
  Set the frequency between samples. Default: 10

### Action Configuration

Action configuration is accessed from the top level of the alarm context. If no specific index is provided, a new action with an unused index will be created. In order to access a existing action the index must be provided.

    example:/config/alarm/#> action
    example:/config/alarm/action-2/#>

`[no] target [TYPE]`

  Add or remove alarm target to an alarm action (profile).

  Note

  Depending on the selected target type, additional configuration options that need to be set can appear. For instance, if the target type port is selected, specific port interfaces needs to be specified.

  no
    Remove any configured targets.
  TYPE

    `led` : ON/Status LED.

    `log` : Log status change to syslog.

    `snmp` : Generate an SNMP trap.

    `digout` : Control the status relay.

    `port` : Control the admin status of a port.

    `iface` : Control the admin status of an interface.

The default action (action 1) has SNMP, Log, LED and Digout (status relay) as targets. For new actions, the default target is ‘Log’.

    example:/config/alarm/#> show action 1
    ID            : 1
    Targets       : snmp log led digout
    example:/config/alarm/#> action 2
    example:/config/alarm/action-2/#> target led
    example:/config/alarm/action-2/#> show
    ID            : 2
    Targets       : log led
    example:/config/alarm/action-2/#>

For ‘port’ and ‘iface’ targets, the associated port(s) or network interface(s) to control must be configured.

    example:/config/alarm/#> action 3
    example:/config/alarm/action-3/#> target port
    example:/config/alarm/action-3/#> port eth6
    example:/config/alarm/action-3/#> show
    ID            : 3
    Targets       : log port
    Ports         : eth6
    example:/config/alarm/action-3/#>

`[no] port <PORT|PORTS>`

  (For ‘target port’) Set which port(s) to control administrative status on.

  no
    Remove configured port.
`[no] iface <IFACE|IFACES>`

  (For ‘target iface’) Set which network interface(s) to control administrative status on.

  no
    Remove configured interface.

## Status

In order to see all the currently configured alarms on the system, the following command can be invoked from the top level in the CLI:

    example:/#> show alarm
    NO TRIGGER          ENA ACT REASON
     1 temperature      YES  NO

If one of the alarms have been triggered, the same command will also display that the alarm is active along with the reason why:

    example:/#> show alarm
    NO TRIGGER          ENA ACT REASON
     1 temperature      YES YES Temperature is 40.75 degrees Celsius

« Previous Next »