salt.engines.napalm_syslog#

NAPALM syslog engine#

New 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#

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:

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.