Chapter 8. Engines
Engines are another interface that interacts directly with the event bus. While beacons are typically used to import events from external source, engines can be designed bidirectionally. That means they can both import external events and translate them into structured data that can be interpreted by Salt, or export Salt events into different services.
Engines Are Easy to Configure
As most Salt subsystems, engines can be configured on the master or the Minion side depending on the application requirements.
They are configured via a top-level section in the master or (proxy) minion configuration. The following example is an excellent way to monitor the entire Salt activity in real time by pushing the events into Logstsh, via HTTP(S):
engine:-http_logstash:url:https://logstash.s.as1234.net/salt
Under the engine section we can define a list of Engines, each having its particular settings. In this example, for the http_logstash engine we have only configured the url of the Logstash instance where to log the Salt events.
There are several engines by default embedded into Salt, any of them having a potential to be used in the network automation environment, directly or indirectly, for various services, including Docker, Logstash, or Redis. Engines can be equally used to facilitate “ChatOps”, where they forward the requests between a common chat application, such as HipChat or Slack, and the Salt master.
napalm-logs and the napalm-syslog Engine
For event-driven, multivendor network automation needs, beginning with the release codename Nitrogen (2017.7), Salt includes an engine called napalm-syslog. It is based on napalm-logs, which is a third-party library provided by the NAPALM Automation community.
The napalm-logs Library and Daemon
Although written and maintained by the NAPALM Automation community, napalm-logs has a radically different approach than the rest of the libraries provided by the same community. While the main goal of the main NAPALM library is to ease the connectivity to various network platforms, napalm-logs is a process running continuously and listening to syslog messages from network devices. The inbound messages can be directly received from the network device, via UDP or TCP, either retrieved from other applications including Apache Kafka, ZeroMQ, Google Datastore, etc. The interface ingesting the raw syslog messages is called listener and is pluggable, so the user can extend the default capabilities by adding another method to receive the messages. napalm-logs processes the textual syslog messages and transforms them into structured objects, in a vendor-agnostic shape. The output objects are JSON serializable, whose structure follows the OpenConfig and IETF YANG models.
For example, the syslog message shown in Example 8-1 is sent by a Juniper device when a NTP server becomes unreachable.
Example 8-1. Raw syslog message from Junos
<99>Jul 13 22:53:14 device1 xntpd[16015]: NTP Server 172.17.17.1 is Unreachable
A similar message, presenting the same notification, sent by a device running IOS-XR, looks like Example 8-2.
Example 8-2. Raw syslog message from IOS-XR
<99>2647599: device3 RP/0/RSP0/CPU0:Aug 21 09:39:14.747 UTC: ntpd[262]: %IP-IP_NTP-5-SYNC_LOSS : Synchronization lost : 172.17.17.1 : The association was removed
The messages examplified here have a totally different structure, although they present the same information. That means, in multivendor networks, we would need to apply different methodologies per platform type to process them.
But using napalm-logs, their representation would be the same, regardless of the platform, as in Example 8-3.
Example 8-3. Structured napalm-logs message example
{"error":"NTP_SERVER_UNREACHABLE","facility":12,"host":"device1","ip":"127.0.0.1","os":"junos","severity":4,"timestamp":1499986394,"yang_message":{"system":{"ntp":{"servers":{"server":{"172.17.17.1":{"state":{"stratum":16,"association-type":"SERVER"}}}}}}},"yang_model":"openconfig-system"}
The object under the yang_message key from Example 8-3 respects the
tree hierarchy standardized in the openconfig-system YANG model.
Note
Each message published by napalm-logs has a unique identification name, specified under the error field which is platform-independent.
yang_model references the name of the YANG model used to map the data from the original syslog message into the structured object.
These output objects are then published over different channels, including ZeroMQ (default), Kafka, TCP, etc. Similar to the listener interface, the publisher is also pluggable.
By default, all the messages published by napalm-logs are encrypted and signed, however this behavior can be disabled—though doing so is highly discouraged.
Due to its flexibility, napalm-logs can be used in various topologies. For example, you might opt for one daemon running in every datacenter, securely publishing the messages to a central collector. Another approach is to simply configure the network devices to send the syslog messages to a napalm-logs process running centrally, where multiple clients can connect to consume the structured messages. But many other possibilities exist beyond these two examples—there are no design constraints!
The napalm-syslog Salt Engine
The napalm-syslog Salt Engine is a simple consumer of the napalm-logs output objects: it connects to the publisher interface, constructs the Salt event tag, and injects the event into the Salt bus. The data of the event is exactly the message received from napalm-logs, while the tag contains the napalm-logs error name, the network operating system name and the hostname of the device that sent the notification (Example 8-4).
Example 8-4. Salt event imported from napalm-logs
napalm/syslog/junos/NTP_SERVER_UNREACHABLE/device1{"yang_message":{...snip...}}