# salt.engines.napalm_syslog

## NAPALM syslog engine

Added in version 2017.7.0.

An engine that takes syslog messages structured in OpenConfig or IETF format and fires Salt events.

As there can be many messages pushed into the event bus, the user is able to filter based on the object structure.

### Requirements

- napalm-logs

This engine transfers objects from the napalm-logs library into the event bus. The top dictionary has the following keys:

- `ip`

- `host`

- `timestamp`

- `os`: the network OS identified

- `model_name`: the OpenConfig or IETF model name

- `error`: the error name (consult the documentation)

- `message_details`: details extracted from the syslog message

- `open_config`: the OpenConfig model

The napalm-logs transfers the messages via widely used transport mechanisms such as: ZeroMQ (default), Kafka, etc.

The user can select the right transport using the `transport` option in the configuration.

configuration:

  Example configuration

      engines:
        - napalm_syslog:
            transport: zmq
            address: 1.2.3.4
            port: 49018

configuration:

  Configuration example, excluding messages from IOS-XR devices:

      engines:
        - napalm_syslog:
            transport: kafka
            address: 1.2.3.4
            port: 49018
            os_blacklist:
              - iosxr

Event example:

    {
        "_stamp": "2017-05-26T10:03:18.653045",
        "error": "BGP_PREFIX_THRESH_EXCEEDED",
        "host": "vmx01",
        "ip": "192.168.140.252",
        "message_details": {
            "date": "May 25",
            "host": "vmx01",
            "message": "192.168.140.254 (External AS 65001): Configured maximum prefix-limit threshold(22) exceeded for inet-unicast nlri: 28 (instance master)",
            "pri": "28",
            "processId": "2957",
            "processName": "rpd",
            "tag": "BGP_PREFIX_THRESH_EXCEEDED",
            "time": "20:50:41"
        },
        "model_name": "openconfig_bgp",
        "open_config": {
            "bgp": {
                "neighbors": {
                    "neighbor": {
                        "192.168.140.254": {
                            "afi_safis": {
                                "afi_safi": {
                                    "inet": {
                                        "afi_safi_name": "inet",
                                        "ipv4_unicast": {
                                            "prefix_limit": {
                                                "state": {
                                                    "max_prefixes": 22
                                                }
                                            }
                                        },
                                        "state": {
                                            "prefixes": {
                                                "received": 28
                                            }
                                        }
                                    }
                                }
                            },
                            "neighbor_address": "192.168.140.254",
                            "state": {
                                "peer_as": 65001
                            }
                        }
                    }
                }
            }
        },
        "os": "junos",
        "timestamp": "1495741841"
    }

To consume the events and eventually react and deploy a configuration changes on the device(s) firing the event, one is able to identify the minion ID, using one of the following alternatives, but not limited to:

- `Host grains` to match the event tag

- `Host DNS grain` to match the IP address in the event data

- `Hostname grains` to match the event tag

- Define static grains

- Write a grains module

- Targeting minions using pillar data - The user can configure certain information in the Pillar data and then use it to identify minions

Master configuration example, to match the event and react:

    reactor:
      - 'napalm/syslog/*/BGP_PREFIX_THRESH_EXCEEDED/*':
        - salt://increase_prefix_limit_on_thresh_exceeded.sls

Which matches the events having the error code `BGP_PREFIX_THRESH_EXCEEDED` from any network operating system, from any host and reacts, executing the `increase_prefix_limit_on_thresh_exceeded.sls` reactor, found under one of the `file_roots` paths.

Reactor example:

    increase_prefix_limit_on_thresh_exceeded:
      local.net.load_template:
        - tgt: "hostname:{{ data['host'] }}"
        - tgt_type: grain
        - kwarg:
            template_name: salt://increase_prefix_limit.jinja
            openconfig_structure: {{ data['open_config'] }}

The reactor in the example increases the BGP prefix limit when triggered by an event as above. The minion is matched using the `host` field from the `data` (which is the body of the event), compared to the `hostname grain` field. When the event occurs, the reactor will execute the `net.load_template` function, sending as arguments the template `salt://increase_prefix_limit.jinja` defined by the user in their environment and the complete OpenConfig object under the variable name `openconfig_structure`. Inside the Jinja template, the user can process the object from `openconfig_structure` and define the bussiness logic as required.

salt.engines.napalm_syslog.start(transport='zmq', address='0.0.0.0', port=49017, auth_address='0.0.0.0', auth_port=49018, disable_security=False, certificate=None, os_whitelist=None, os_blacklist=None, error_whitelist=None, error_blacklist=None, host_whitelist=None, host_blacklist=None)

  Listen to napalm-logs and publish events into the Salt event bus.

  transport: `zmq`

    Choose the desired transport.

    Note

    Currently `zmq` is the only valid option.

  address: `0.0.0.0`

    The address of the publisher, as configured on napalm-logs.

  port: `49017`

    The port of the publisher, as configured on napalm-logs.

  auth_address: `0.0.0.0`

    The address used for authentication when security is not disabled.

  auth_port: `49018`

    Port used for authentication.

  disable_security: `False`

    Trust unencrypted messages. Strongly discouraged in production.

  certificate: `None`

    Absolute path to the SSL certificate.

  os_whitelist: `None`

    List of operating systems allowed. By default everything is allowed.

  os_blacklist: `None`

    List of operating system to be ignored. Nothing ignored by default.

  error_whitelist: `None`

    List of errors allowed.

  error_blacklist: `None`

    List of errors ignored.

  host_whitelist: `None`

    List of hosts or IPs to be allowed.

  host_blacklist: `None`

    List of hosts of IPs to be ignored.