Merge pull request #291 from paulgear/master

API additions and updates; minor tidies
2024-10-07 16:52:45 +00:00 · 2014-09-28 11:06:22 +10:00
parent e0d8011c29 11f475b405
commit 0852cb34dd
8 changed files with 116 additions and 67 deletions
--- a/delhost.php
+++ b/delhost.php
@@ -28,8 +28,7 @@ if ($argv[1])
  $id = getidbyname($host);
  if ($id)
  {
-    echo(delete_device($id));
-    echo("Removed $host\n");
+    echo(delete_device($id)."\n");
  } else {
    echo("Host doesn't exist!\n");
  }
--- a/html/api_v0.php
+++ b/html/api_v0.php
@@ -30,9 +30,10 @@ $app->setName('api');
 $app->group('/api', function() use ($app) {
  $app->group('/v0', function() use ($app) {
    $app->group('/devices', function() use ($app) {
-      $app->get('/:hostname/ports/:ifname/:type', 'authToken', 'get_graph_by_port_hostname');//api/v0/devices/$hostname/ports/$ifName/$type
+      $app->get('/:hostname', 'authToken', 'get_device');//api/v0/devices/$hostname
      $app->get('/:hostname/:type', 'authToken', 'get_graph_generic_by_hostname');//api/v0/devices/$hostname/$type
      $app->get('/:hostname/ports/:ifname', 'authToken', 'get_port_stats_by_port_hostname');//api/v0/devices/$hostname/ports/$ifName
+      $app->get('/:hostname/ports/:ifname/:type', 'authToken', 'get_graph_by_port_hostname');//api/v0/devices/$hostname/ports/$ifName/$type
    });
    $app->get('/devices', 'authToken', 'list_devices');//api/v0/devices
    $app->post('/devices', 'authToken', 'add_device');//api/v0/devices (json data needs to be passed)
--- a/html/includes/api_functions.inc.php
+++ b/html/includes/api_functions.inc.php
@@ -176,8 +176,8 @@ function authToken(\Slim\Route $route)

  if($authenticated === false)
  {
-    $app->response->setStatus(400);
-    $output = array("status" => "error", "message" => "API Token is invalid");
+    $app->response->setStatus(403);
+    $output = array("status" => "error", "message" => "API Token is missing or invalid; please supply a valid token");
    echo _json_encode($output);
    $app->stop();
  }
@@ -247,6 +247,33 @@ function get_graph_generic_by_hostname()
  require("includes/graphs/graph.inc.php");
 }

+function get_device()
+{
+  // return details of a single device
+  $app = \Slim\Slim::getInstance();
+  $app->response->headers->set('Content-Type', 'application/json');
+  $router = $app->router()->getCurrentRoute()->getParams();
+  $hostname = $router['hostname'];
+
+  require_once("../includes/functions.php");
+
+  // use hostname as device_id if it's all digits
+  $device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
+
+  // find device matching the id
+  $device = device_by_id_cache($device_id);
+  if (!$device) {
+    $app->response->setStatus(404);
+    $output = array("status" => "error", "message" => "Device $hostname does not exist");
+    echo _json_encode($output);
+    $app->stop();
+  }
+  else {
+    $output = array("status" => "ok", "devices" => array($device));
+    echo _json_encode($output);
+  }
+}
+
 function list_devices()
 {
  // This will return a list of devices
@@ -299,11 +326,15 @@ function list_devices()
 function add_device()
 {
  // This will add a device using the data passed encoded with json
+  // FIXME: Execution flow through this function could be improved
  global $config;
  $app = \Slim\Slim::getInstance();
  $data = json_decode(file_get_contents('php://input'), true);
-  // Default status to error and change it if we need to.
+  // Default status & code to error and change it if we need to.
  $status = "error";
+  $code = 500;
+  // keep scrutinizer from complaining about snmpver not being set for all execution paths
+  $snmpver = "v2c";
  if(empty($data))
  {
    $message = "No information has been provided to add this new device";
@@ -313,8 +344,8 @@ function add_device()
    $message = "Missing the device hostname";
  }
  $hostname = $data['hostname'];
-  if ($data['port']) { $port = mres($data['port']); } else { $port = $config['snmp']['port']; }
-  if ($data['transport']) { $transport = mres($data['transport']); } else { $transport = "udp"; }
+  $port = $data['port'] ? mres($data['port']) : $config['snmp']['port'];
+  $transport = $data['transport'] ? mres($data['transport']) : "udp";
  if($data['version'] == "v1" || $data['version'] == "v2c")
  {
    if ($data['community'])
@@ -339,6 +370,8 @@ function add_device()
  }
  else
  {
+    $code = 400;
+    $status = "error";
    $message = "You haven't specified an SNMP version to use";
  }
  if(empty($message))
@@ -347,8 +380,9 @@ function add_device()
    $result = addHost($hostname, $snmpver, $port, $transport, 1);
    if($result)
    {
-      $status = 'ok';
-      $message = 'Device has been added successfully';
+      $code = 201;
+      $status = "ok";
+      $message = "Device $hostname has been added successfully";
    }
    else
    {
@@ -356,6 +390,7 @@ function add_device()
    }
  }

+  $app->response->setStatus($code);
  $output = array("status" => $status, "message" => $message);
  $app->response->headers->set('Content-Type', 'application/json');
  echo _json_encode($output);
@@ -371,30 +406,44 @@ function del_device()
  $hostname = $router['hostname'];
  // Default status to error and change it if we need to.
  $status = "error";
+  $code = 500;
  if(empty($hostname))
  {
-    $message = "No hostname has been provided to delete this device";
+    $message = "No hostname has been provided to delete";
+    $output = array("status" => $status, "message" => $message);
  }
-  elseif(empty($hostname))
-  {
-    $message = "Missing the device hostname";
-  }
-  if(empty($message))
+  else
  {
    require_once("../includes/functions.php");
-    $device_id = get_device_id($hostname);
-    $response = delete_device($device_id);
-    if(empty($response))
-    {
-      $message = "Device couldn't be deleted";
+
+    // allow deleting by device_id or hostname
+    $device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
+    $device = null;
+    if ($device_id) {
+      // save the current details for returning to the client on successful delete
+      $device = device_by_id_cache($device_id);
    }
-    else
-    {
-      $message = $response;
-      $status = "ok";
+    if ($device) {
+      $response = delete_device($device_id);
+      if(empty($response)) {
+	// FIXME: Need to provide better diagnostics out of delete_device
+	$output = array("status" => $status, "message" => "Device deletion failed");
+      }
+      else {
+	// deletion succeeded - include old device details in response
+	$code = 200;
+	$status = "ok";
+	$output = array("status" => $status, "message" => $response, "devices" => array($device));
+      }
+    }
+    else {
+      // no device matching the name
+      $code = 404;
+      $output = array("status" => $status, "message" => "Device $hostname not found");
    }
  }
-  $output = array("status" => $status, "message" => $message);
+
+  $app->response->setStatus($code);
  $app->response->headers->set('Content-Type', 'application/json');
  echo _json_encode($output);
 }
--- a/html/index.php
+++ b/html/index.php
@@ -288,9 +288,10 @@ if (is_array($pagetitle))
      <div class="col-md-12 text-center">
 <?php
 echo('        <br /> <br />  ' . (isset($config['footer']) ? $config['footer'] : ''));
-echo('        <br />Powered by <a href="' . $config['project_url'] . '" target="_blank">' . $config['project_name_version'].'</a>. ');
+echo('        <br />Powered by <a href="' . $config['project_url'] . '" target="_blank">' . $config['project_name_version'].'</a>.<br/>');
 echo(         $config['project_name'].' is <a href="http://www.gnu.org/philosophy/free-sw.html">Free Software</a>, released under the <a href="http://www.gnu.org/copyleft/gpl.html">GNU GPLv3</a>.<br/>');
-echo('        Copyright &copy; 2006-2012 by Adam Armstrong. Copyright &copy; 2013-'.date("Y").' by the '.$config['project_name'].' Contributors.');
+echo('        Copyright &copy; 2013-'.date("Y").' by the '.$config['project_name'].' Contributors.<br/>');
+echo('        Copyright &copy; 2006-2012 by Adam Armstrong.');
 ?>
      </div>
    </div>
--- a/html/pages/api-docs.inc.php
+++ b/html/pages/api-docs.inc.php
@@ -67,7 +67,7 @@ if ($_SESSION['userlevel'] == '10')
        </tr>
        <tr>
          <td>/api</td>
-          <td>/v1</td>
+          <td>/v0</td>
          <td>/devices/$hostname/ports/$ifName/$type</td>
          <td>
            <ul class="list-unstyled">
@@ -85,10 +85,28 @@ if ($_SESSION['userlevel'] == '10')
          </td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices/localhost/ports/eth0/port_bits" > /tmp/graph.png</code></td>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/ports/eth0/port_bits" > /tmp/graph.png</code></td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices/localhost/ports/eth0/port_bits?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png</code></td>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/ports/eth0/port_bits?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png</code></td>
+        </tr>
+        <a name="general_info"></a>
+        <tr class="success">
+          <td colspan="5"><strong>General Info</strong></td>
+        </tr>
+        <tr>
+          <td>/api</td>
+          <td>/v0</td>
+          <td>/devices/$hostname</td>
+          <td>
+            <ul class="list-unstyled">
+              <li>$hostname = the hostname of the device you want the information about</li>
+            </ul>
+          </td>
+          <td>JSON</td>
+        </tr>
+        <tr>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost" > localhost.json</code></td>
        </tr>
        <a name="general_graphs"></a>
        <tr class="success">
@@ -96,7 +114,7 @@ if ($_SESSION['userlevel'] == '10')
        </tr>
        <tr>
          <td>/api</td>
-          <td>/v1</td>
+          <td>/v0</td>
          <td>/devices/$hostname/$type</td>
          <td>
            <ul class="list-unstyled">
@@ -113,10 +131,10 @@ if ($_SESSION['userlevel'] == '10')
          </td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices/localhost/device_processor" > /tmp/graph.png</code></td>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/device_processor" > /tmp/graph.png</code></td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices/localhost/device_processor?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png</code></td>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/device_processor?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png</code></td>
        </tr>
        <a name="port_stats"></a>
        <tr class="success">
@@ -124,7 +142,7 @@ if ($_SESSION['userlevel'] == '10')
        </tr>
        <tr>
          <td>/api</td>
-          <td>/v1</td>
+          <td>/v0</td>
          <td>/devices/$hostname/ports/$ifName</td>
          <td>
            <ul class="list-unstyled">
@@ -137,7 +155,7 @@ if ($_SESSION['userlevel'] == '10')
          </td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices/localhost/ports/eth0"</code></td>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/ports/eth0"</code></td>
        </tr>
        <a name="list"></a>
        <tr class="success">
@@ -145,8 +163,8 @@ if ($_SESSION['userlevel'] == '10')
        </tr>
        <tr>
          <td>/api</td>
-          <td>/v1</td>
-          <td>/list/devices</td>
+          <td>/v0</td>
+          <td>/devices</td>
          <td>
            <ul class="list-unstyled">
              <li>$order = the name of the column to order by</li>
@@ -158,10 +176,10 @@ if ($_SESSION['userlevel'] == '10')
          </td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices"</code></td>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices"</code></td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices?order=hostname&type=all"</code></td>
+          <td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices?order=hostname&type=all"</code></td>
        </tr>
        <a name="add"></a>
        <tr class="success">
@@ -169,7 +187,7 @@ if ($_SESSION['userlevel'] == '10')
        </tr>
        <tr>
          <td>/api</td>
-          <td>/v1</td>
+          <td>/v0</td>
          <td>/devices</td>
          <td>
            <ul class="list-unstyled">
@@ -191,7 +209,7 @@ if ($_SESSION['userlevel'] == '10')
          </td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}' \<br />-H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices"</code></td>
+          <td colspan="5"><code>curl -X POST -d '{"hostname":"localhost.localdomain","version":"v0","community":"public"}' \<br />-H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices"</code></td>
        </tr>
        <a name="delete"></a>
        <tr class="success">
@@ -199,7 +217,7 @@ if ($_SESSION['userlevel'] == '10')
        </tr>
        <tr>
          <td>/api</td>
-          <td>/v1</td>
+          <td>/v0</td>
          <td>/devices/$hostname</td>
          <td>
            <ul class="list-unstyled">
@@ -211,7 +229,7 @@ if ($_SESSION['userlevel'] == '10')
          </td>
        </tr>
        <tr>
-          <td colspan="5"><code>curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v1/devices/localhost"</code></td>
+          <td colspan="5"><code>curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost"</code></td>
        </tr>
      </table>
    </div>
--- a/html/pages/delhost.inc.php
+++ b/html/pages/delhost.inc.php
@@ -19,7 +19,7 @@ if (is_numeric($_REQUEST['id']))
 ');
  if ($_REQUEST['confirm'])
  {
-    print_message(delete_device(mres($_REQUEST['id'])));
+    print_message(delete_device(mres($_REQUEST['id']))."\n");
  }
  else
  {
--- a/includes/functions.php
+++ b/includes/functions.php
@@ -248,7 +248,7 @@ function delete_device($id)

  shell_exec("rm -rf ".trim($config['rrd_dir'])."/$host");

-  $ret = "Removed device $host\n";
+  $ret = "Removed device $host";
  return $ret;
 }

@@ -941,25 +941,4 @@ function validate_device_id($id)
  return($return);
 }

-function get_device_id($hostname)
-{
-  global $config;
-  if(empty($hostname))
-  {
-    $return = false;
-  }
-  else
-  {
-    $device_id = dbFetchCell("SELECT `device_id` FROM `devices` WHERE `hostname` = ?", array($hostname));
-    if(empty($device_id))
-    {
-      $return = false;
-    }
-    else
-    {
-      $return = $device_id;
-    }
-  }
-  return $return;
-}
 ?>
--- a/sql-schema/034.sql
+++ b/sql-schema/034.sql
@@ -0,0 +1,2 @@
+-- Allow for future use of different tokens - this supports up to SHA-512
+ALTER TABLE `api_tokens` MODIFY `token_hash` VARCHAR(256);