README.md
1# napalm-logs
2
3napalm-logs is a Python library that listens to syslog messages from network
4devices and returns structured data following the [OpenConfig](http://www.openconfig.net/)
5or [IETF](https://github.com/YangModels/yang/tree/master/standard/ietf) YANG models.
6
7<img src="logo.png" data-canonical-src="logo.png" width="300" />
8
9The outgoing objects are published via ZeroMQ, Kafka, or other usual transport
10options. It is easy enough to switch between transports and pluggable to add
11others such as Google Datastore, RabbitMQ, etc.
12
13Similarly, the syslog messages can be received via UDP, TCP, or different
14services, such as Kafka, etc.
15
16New platforms can be easily added, just referencing the path to the
17YAML configuration file.
18
19Requirements
20------------
21
22- PyYAML
23- PyZMQ
24- PyNaCl
25- u-msgpack-python
26
27Output object example
28---------------------
29
30```json
31{
32 "yang_message": {
33 "bgp": {
34 "neighbors": {
35 "neighbor": {
36 "192.168.140.254": {
37 "state": {
38 "peer_as": "65001"
39 },
40 "afi_safis": {
41 "afi_safi": {
42 "inet4": {
43 "state": {
44 "prefixes": {
45 "received": 141
46 }
47 },
48 "ipv4_unicast": {
49 "prefix_limit": {
50 "state": {
51 "max_prefixes": 140
52 }
53 }
54 }
55 }
56 }
57 }
58 }
59 }
60 }
61 }
62 },
63 "message_details": {
64 "processId": "2902",
65 "facility": 18,
66 "severity": 5,
67 "hostPrefix": null,
68 "pri": "149",
69 "processName": "rpd",
70 "host": "vmx01",
71 "tag": "BGP_PREFIX_THRESH_EXCEEDED",
72 "time": "14:03:12",
73 "date": "Jun 21",
74 "message": "192.168.140.254 (External AS 65001): Configured maximum prefix-limit threshold(140) exceeded for inet4-unicast nlri: 141 (instance master)"
75 },
76 "timestamp": 1498050192,
77 "facility": 18,
78 "ip": "127.0.0.1",
79 "host": "vmx01",
80 "yang_model": "openconfig-bgp",
81 "error": "BGP_PREFIX_THRESH_EXCEEDED",
82 "os": "junos",
83 "severity": 5
84}
85```
86
87Documentation
88-------------
89
90Please check [the official documentation](http://napalm-logs.readthedocs.io/en/latest/) for more detailed information.
91
92Installation
93------------
94
95```
96pip install napalm-logs
97```
98
README.rst
1===========
2Napalm-logs
3===========
4
5Python library to parse syslog messages from network devices and produce JSON serializable Python objects, in a vendor agnostic shape. The output objects are structured following the OpenConfig or IETF YANG models.
6
7For example, the following syslog message from a Juniper device:
8
9.. code-block:: text
10
11 Mar 30 12:45:19 re0.edge01.bjm01 rpd[15852]: BGP_PREFIX_THRESH_EXCEEDED 1.2.3.4 (External AS 15169): Configured maximum prefix-limit threshold(160) exceeded for inet-unicast nlri: 181 (instance master)
12
13
14Will produce the following object:
15
16.. code-block:: json
17
18 {
19 "yang_message": {
20 "bgp": {
21 "neighbors": {
22 "neighbor": {
23 "192.168.140.254": {
24 "state": {
25 "peer_as": "65001"
26 },
27 "afi_safis": {
28 "afi_safi": {
29 "inet4": {
30 "state": {
31 "prefixes": {
32 "received": 141
33 }
34 },
35 "ipv4_unicast": {
36 "prefix_limit": {
37 "state": {
38 "max_prefixes": 140
39 }
40 }
41 }
42 }
43 }
44 }
45 }
46 }
47 }
48 }
49 },
50 "message_details": {
51 "processId": "2902",
52 "severity": 5,
53 "facility": 18,
54 "hostPrefix": null,
55 "pri": "149",
56 "processName": "rpd",
57 "host": "vmx01",
58 "tag": "BGP_PREFIX_THRESH_EXCEEDED",
59 "time": "14:03:12",
60 "date": "Jun 21",
61 "message": "192.168.140.254 (External AS 65001): Configured maximum prefix-limit threshold(140) exceeded for inet4-unicast nlri: 141 (instance master)"
62 },
63 "timestamp": 1498050192,
64 "facility": 18,
65 "ip": "127.0.0.1",
66 "host": "vmx01",
67 "yang_model": "openconfig-bgp",
68 "error": "BGP_PREFIX_THRESH_EXCEEDED",
69 "os": "junos",
70 "severity": 5
71 }
72 }
73
74The library is comes with a command line program which acts as a daemon, running in background and listening to syslog messages continuously, then publishing them over secured channels, where multiple clients can subscribe.
75
76It is flexible to listen to the syslog messages via UDP or TCP, but also from brokers such as Apache Kafka. Similarly, the output objects can be published via various channels such as ZeroMQ, Kafka, or remote server logging. It is also pluggable enough to extend these capabilities and listen or publish to other services, depending on the needs.
77
78The messages are published over a secured channel, encrypted and signed. Although the security can be disabled, this is highly discouraged.
79
80Documentation
81--------------
82
83Please check `the official documentation <http://napalm-logs.readthedocs.io/en/latest/>`_ for more detailed information.
84
85Install
86-------
87napalm-logs is available on PyPi and can easily be installed using the following command:
88
89.. code-block:: bash
90
91 pip install napalm-logs
92
