# salt.beacons.napalm_beacon

## Watch NAPALM functions and fire events on specific triggers

Added in version 2018.3.0.

Note

The `NAPALM` beacon only works only when running under a regular Minion or a Proxy Minion, managed via NAPALM. Check the documentation for the `NAPALM proxy module`.

The configuration accepts a list of Salt functions to be invoked, and the corresponding output hierarchy that should be matched against. To invoke a function with certain arguments, they can be specified using the `_args` key, or `_kwargs` for more specific key-value arguments.

The match structure follows the output hierarchy of the NAPALM functions, under the `out` key.

For example, the following is normal structure returned by the `ntp.stats` execution function:

    {
        "comment": "",
        "result": true,
        "out": [
            {
                "referenceid": ".GPSs.",
                "remote": "172.17.17.1",
                "synchronized": true,
                "reachability": 377,
                "offset": 0.461,
                "when": "860",
                "delay": 143.606,
                "hostpoll": 1024,
                "stratum": 1,
                "jitter": 0.027,
                "type": "-"
            },
            {
                "referenceid": ".INIT.",
                "remote": "172.17.17.2",
                "synchronized": false,
                "reachability": 0,
                "offset": 0.0,
                "when": "-",
                "delay": 0.0,
                "hostpoll": 1024,
                "stratum": 16,
                "jitter": 4000.0,
                "type": "-"
            }
        ]
    }

In order to fire events when the synchronization is lost with one of the NTP peers, e.g., `172.17.17.2`, we can match it explicitly as:

    ntp.stats:
      remote: 172.17.17.2
      synchronized: false

There is one single nesting level, as the output of `ntp.stats` is just a list of dictionaries, and this beacon will compare each dictionary from the list with the structure examplified above.

Note

When we want to match on any element at a certain level, we can configure `*` to match anything.

Considering a more complex structure consisting on multiple nested levels, e.g., the output of the `bgp.neighbors` execution function, to check when any neighbor from the `global` routing table is down, the match structure would have the format:

    bgp.neighbors:
      global:
        '*':
          up: false

The match structure above will match any BGP neighbor, with any network (`*` matches any AS number), under the `global` VRF. In other words, this beacon will push an event on the Salt bus when there's a BGP neighbor down.

The right operand can also accept mathematical operations (i.e., `<`, `<=`, `!=`, `>`, `>=` etc.) when comparing numerical values.

Configuration Example:

    beacons:
      napalm:
        - net.interfaces:
            # fire events when any interfaces is down
            '*':
              is_up: false
        - net.interfaces:
            # fire events only when the xe-0/0/0 interface is down
            'xe-0/0/0':
              is_up: false
        - ntp.stats:
            # fire when there's any NTP peer unsynchornized
            synchronized: false
        - ntp.stats:
            # fire only when the synchronization
            # with with the 172.17.17.2 NTP server is lost
            _args:
              - 172.17.17.2
            synchronized: false
        - ntp.stats:
            # fire only when there's a NTP peer with
            # synchronization stratum > 5
            stratum: '> 5'

Event structure example:

    {
        "_stamp": "2017-09-05T09:51:09.377202",
        "args": [],
        "data": {
            "comment": "",
            "out": [
                {
                    "delay": 0.0,
                    "hostpoll": 1024,
                    "jitter": 4000.0,
                    "offset": 0.0,
                    "reachability": 0,
                    "referenceid": ".INIT.",
                    "remote": "172.17.17.1",
                    "stratum": 16,
                    "synchronized": false,
                    "type": "-",
                    "when": "-"
                }
            ],
            "result": true
        },
        "fun": "ntp.stats",
        "id": "edge01.bjm01",
        "kwargs": {},
        "match": {
            "stratum": "> 5"
        }
    }

The event examplified above has been fired when the device identified by the Minion id `edge01.bjm01` has been synchronized with a NTP server at a stratum level greater than 5.

salt.beacons.napalm_beacon.beacon(config)

  Watch napalm function and fire events.

salt.beacons.napalm_beacon.validate(config)

  Validate the beacon configuration.