feature: Added Syslog hooks for Oxidized integration (and more) (#6785)

* Creating syslog hooks with example script for Oxidized integration

* Corrected IOS-XR matching and stopped spurious calls to Oxidized

doc/Extensions/Oxidized.md

@@ -121,3 +121,10 @@ $config['oxidized']['ignore_types'] = array('server');
 $config['oxidized']['ignore_os'] = array('linux');
 ```
 
+### Trigger configuration downloads
+
+Using the Oxidized REST API and [Syslog Hooks](/Extensions/Syslog/#external-hooks), Oxidized can trigger configuration downloads whenever a configuration change event has been logged. An example script to do this is included in `./scripts/syslog-notify-oxidized.php`. Oxidized can spawn a new worker thread and perform the download immediately with the following configuration
+
+```bash
+next_adds_job: true
+```

doc/Extensions/Syslog.md

@@ -78,7 +78,7 @@ Next start syslog-ng:
 service syslog-ng restart
 ```
 
-Add the following to your LibreNMS config.php file to enable the Syslog extension:
+Add the following to your LibreNMS `config.php` file to enable the Syslog extension:
 
 ```ssh
 $config['enable_syslog'] = 1;
@@ -171,3 +171,28 @@ logging server librenms.ip 5 use-vrf default facility local6
 ```
 
 If you have permitted udp and tcp 514 through any firewall then that should be all you need. Logs should start appearing and displayed within the LibreNMS web UI.
+
+### External hooks
+
+Trigger external scripts based on specific syslog patterns being matched with syslog hooks. Add the following to your LibreNMS `config.php` to enable hooks:
+
+```ssh
+$config['enable_syslog_hooks'] = 1;
+```
+
+The below are some example hooks to call an external script in the event of a configuration change on Cisco IOS, IOS-XR and NX-OS devices. Add to your `config.php` file to enable.
+
+#### Cisco IOS
+```ssh
+$config['os']['ios']['syslog_hook'][] = Array('regex' => '/%SYS-(SW[0-9]+-)?5-CONFIG_I/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
+```
+
+#### Cisco NXOS
+```ssh
+$config['os']['nxos']['syslog_hook'][] = Array('regex' => '/%VSHD-5-VSHD_SYSLOG_CONFIG_I/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
+```
+
+#### Cisco IOSXR
+```ssh
+$config['os']['iosxr']['syslog_hook'][] = Array('regex' => '/%GBL-CONFIG-6-DB_COMMIT/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
+```

includes/syslog.php

@@ -33,6 +33,10 @@ function get_cache($host, $value)
                 $dev_cache[$host]['version'] = dbFetchCell('SELECT `version` FROM devices WHERE `device_id`= ?', array(get_cache($host, 'device_id')));
                 break;
 
+            case 'hostname':
+                $dev_cache[$host]['hostname'] = dbFetchCell('SELECT `hostname` FROM devices WHERE `device_id` = ?', array(get_cache($host, 'device_id')));
+                break;
+
             default:
                 return null;
         }//end switch
@@ -56,6 +60,15 @@ function process_syslog($entry, $update)
     $entry['device_id'] = get_cache($entry['host'], 'device_id');
     if ($entry['device_id']) {
         $os = get_cache($entry['host'], 'os');
+        $hostname = get_cache($entry['host'], 'hostname');
+
+        if ((isset($config['enable_syslog_hooks'])) && ($config['enable_syslog_hooks']) && (isset($config['os'][$os]['syslog_hook'])) && (is_array($config['os'][$os]['syslog_hook']))) {
+            foreach ($config['os'][$os]['syslog_hook'] as $k => $v) {
+                if ((isset($v['script'])) && (isset($v['regex'])) && (preg_match($v['regex'], $entry['msg']))) {
+                    shell_exec(escapeshellcmd($v['script']).' '.escapeshellarg($hostname).' '.escapeshellarg($os).' '.escapeshellarg($entry['msg']).' >/dev/null 2>&1 &');
+                }
+            }
+        }
 
         if (in_array($os, array('ios', 'iosxe', 'catos'))) {
             // multipart message

scripts/syslog-notify-oxidized.php

@@ -0,0 +1,38 @@
+#!/usr/bin/env php
+<?php
+
+$init_modules = array();
+require __DIR__ . '/../includes/init.php';
+
+function oxidized_node_update($hostname, $username, $msg)
+{
+    global $config;
+
+    // Work around https://github.com/rack/rack/issues/337
+    $msg = str_replace("%", "", $msg);
+    $postdata = array("user" => $username, "msg" => $msg);
+
+    $version = `git rev-parse --short HEAD`;
+    if ($version != "") {
+        $version = "/".$version;
+    }
+
+    $curl = curl_init();
+    curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
+    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($postdata));
+    curl_setopt($curl, CURLOPT_USERAGENT, "librenms".$version);
+    curl_setopt($curl, CURLOPT_URL, $config['oxidized']['url'].'/node/next/'.$hostname);
+    $result = curl_exec($curl);
+}//end oxidized_node_update()
+
+$hostname = $argv[1];
+$os = $argv[2];
+$msg = $argv[3];
+
+if (preg_match('/(SYS-(SW[0-9]+-)?5-CONFIG_I|VSHD-5-VSHD_SYSLOG_CONFIG_I): Configured from .+ by (?P<user>.+) on .*/', $msg, $matches)) {
+    $username = $matches['user'];
+    oxidized_node_update($hostname, $username, $msg);
+} elseif (preg_match('/GBL-CONFIG-6-DB_COMMIT : Configuration committed by user \\\\\'(?P<user>.+)\\\\\'..*/', $msg, $matches)) {
+    $username = $matches['user'];
+    oxidized_node_update($hostname, $username, $msg);
+}

tests/SyslogTest.php

@@ -67,7 +67,7 @@ class SyslogTest extends \PHPUnit_Framework_TestCase
     {
         // populate fake $dev_cache and $config
         global $config, $dev_cache;
-        $dev_cache['1.1.1.1'] = array('device_id' => 1, 'os' => 'ios', 'version' => 1);
+        $dev_cache['1.1.1.1'] = array('device_id' => 1, 'os' => 'ios', 'version' => 1, 'hostname' => 'cisco-switch1');
         $config = array();
         $config['syslog_filter'] = array();
 
@@ -149,7 +149,7 @@ class SyslogTest extends \PHPUnit_Framework_TestCase
     {
         // populate fake $dev_cache and $config
         global $config, $dev_cache;
-        $dev_cache['1.1.1.1'] = array('device_id' => 1, 'os' => 'linux', 'version' => 1);
+        $dev_cache['1.1.1.1'] = array('device_id' => 1, 'os' => 'linux', 'version' => 1, 'hostname' => 'linux-server1');
         $config = array();
         $config['syslog_filter'] = array();
 
@@ -202,7 +202,7 @@ class SyslogTest extends \PHPUnit_Framework_TestCase
     {
         // populate fake $dev_cache and $config
         global $config, $dev_cache;
-        $dev_cache['1.1.1.1'] = array('device_id' => 1, 'os' => 'procurve', 'version' => 1);
+        $dev_cache['1.1.1.1'] = array('device_id' => 1, 'os' => 'procurve', 'version' => 1, 'hostname' => 'procurve-switch1');
         $config = array();
         $config['syslog_filter'] = array();