Difference between revisions of "Gateways"

From RackTables Wiki
Jump to navigation Jump to search
m (→‎File layout: fix mind slip)
(Reformat the tables for a more modern visual style.)
 
(12 intermediate revisions by 2 users not shown)
Line 8: Line 8:
 
==List of device breeds==
 
==List of device breeds==
 
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
 
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:
{| border=1 cellspacing=0 cellpadding=5
+
{| class="wikitable"
 +
!Breed Code
 +
!Description
 +
|-
 
| <tt>air12</tt>
 
| <tt>air12</tt>
 
| Cisco Aironet IOS release 12.x
 
| Cisco Aironet IOS release 12.x
Line 23: Line 26:
 
| <tt>ftos8</tt>
 
| <tt>ftos8</tt>
 
| Force10 FTOS release 8.x
 
| Force10 FTOS release 8.x
 +
|-
 +
| <tt>hpprocurveN1178</tt>
 +
| HP N.11.78
 
|-
 
|-
 
| <tt>ios12</tt>
 
| <tt>ios12</tt>
 
| Cisco Catalyst IOS release 12.x
 
| Cisco Catalyst IOS release 12.x
 +
|-
 +
| <tt>ios15</tt>
 +
| Cisco IOS release 15.x
 
|-
 
|-
 
| <tt>iosxr4</tt>
 
| <tt>iosxr4</tt>
Line 50: Line 59:
 
| <tt>vrp55</tt>
 
| <tt>vrp55</tt>
 
| Huawei VRP releases 5.5 and 5.7
 
| Huawei VRP releases 5.5 and 5.7
 +
|-
 +
| <tt>vrp85</tt>
 +
| Huawei VRP release 8.5
 
|-
 
|-
 
| <tt>xos12</tt>
 
| <tt>xos12</tt>
Line 56: Line 68:
  
 
==List of device commands==
 
==List of device commands==
{| border=1 cellspacing=0 cellpadding=5
+
{| class="wikitable"
 +
!Command Code
 +
!Description
 +
|-
 
| <tt>xlatepushq</tt>
 
| <tt>xlatepushq</tt>
 
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
 
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
Line 73: Line 88:
 
|-
 
|-
 
| <tt>getmaclist</tt>
 
| <tt>getmaclist</tt>
| Returns the MAC address table as an array.
+
| Returns the MAC address table (for all ports) as an array.
 +
|-
 +
| <tt>getportmaclist</tt>
 +
| Returns the MAC address table (for a specific port only) as an array.
 
|-
 
|-
 
| <tt>getportstatus</tt>
 
| <tt>getportstatus</tt>
Line 81: Line 99:
 
| Returns a list of hardware components as an array.
 
| Returns a list of hardware components as an array.
 
|}
 
|}
 +
 
==Implementation matrix==
 
==Implementation matrix==
{| border=1 cellspacing=0 cellpadding=5
+
{| class="wikitable" style="text-align:center;"
 
|
 
|
| <tt>xlatepushq</tt>
+
! <tt>xlatepushq</tt>
| <tt>get8021q</tt>
+
! <tt>get8021q</tt>
| <tt>getallconf</tt>
+
! <tt>getallconf</tt>
| <tt>getcdpstatus</tt>
+
! <tt>getcdpstatus</tt>
| <tt>getlldpstatus</tt>
+
! <tt>getlldpstatus</tt>
| <tt>getmaclist</tt>
+
! <tt>getmaclist</tt>
| <tt>getportstatus</tt>
+
! <tt>getportmaclist</tt>
| <tt>getinventory</tt>
+
! <tt>getportstatus</tt>
 +
! <tt>getinventory</tt>
 
|-
 
|-
| <tt>air12</tt>
+
! style="text-align:left;" | <tt>air12</tt>
| bgcolor=green |
+
| &#10003;
 +
|
 +
| &#10003;
 
|  
 
|  
| bgcolor=green |
 
 
|  
 
|  
 
|  
 
|  
Line 103: Line 124:
 
|  
 
|  
 
|-
 
|-
| <tt>dlink</tt>
+
! style="text-align:left;" | <tt>dlink</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
 
|  
 
|  
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>eos4</tt>
+
! style="text-align:left;" | <tt>eos4</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>fdry5</tt>
+
! style="text-align:left;" | <tt>fdry5</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
 
|  
 
|  
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 
|  
 
|  
 +
|-
 +
! style="text-align:left;" | <tt>ftos8</tt>
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 
|  
 
|  
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>ftos8</tt>
+
! style="text-align:left;" | <tt>hpprocurveN1178</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>ios12</tt>
+
! style="text-align:left;" | <tt>ios12</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 +
|  
 +
|-
 +
! style="text-align:left;" | <tt>ios15</tt>
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>iosxr4</tt>
+
! style="text-align:left;" | <tt>iosxr4</tt>
| bgcolor=green |
+
| &#10003;
 +
|
 +
| &#10003;
 
|  
 
|  
| bgcolor=green |
 
 
|  
 
|  
 
|  
 
|  
Line 163: Line 212:
 
|  
 
|  
 
|-
 
|-
| <tt>jun10</tt>
+
! style="text-align:left;" | <tt>jun10</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
|  
 
|  
 
|  
 
|  
 
|  
Line 173: Line 223:
 
|  
 
|  
 
|-
 
|-
| <tt>linux</tt>
+
! style="text-align:left;" | <tt>linux</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
 
|  
 
|  
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>nxos4</tt>
+
! style="text-align:left;" | <tt>nxos4</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>ros11</tt>
+
! style="text-align:left;" | <tt>ros11</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>ucs</tt>
+
! style="text-align:left;" | <tt>ucs</tt>
| bgcolor=green |
+
| &#10003;
 +
|  
 
|  
 
|  
 
|  
 
|  
Line 211: Line 265:
 
|  
 
|  
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
 
|-
 
|-
| <tt>vrp53</tt>
+
! style="text-align:left;" | <tt>vrp53</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>vrp55</tt>
+
! style="text-align:left;" | <tt>vrp55</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|-
 
|-
| <tt>xos12</tt>
+
! style="text-align:left;" | <tt>vrp85</tt>
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
| bgcolor=green |
+
| &#10003;
 
|  
 
|  
| bgcolor=green |
+
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 
|  
 
|  
 +
|-
 +
! style="text-align:left;" | <tt>xos12</tt>
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 
|  
 
|  
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 +
| &#10003;
 
|  
 
|  
 
|}
 
|}
Line 261: Line 329:
 
;
 
;
  
==Key API funcrions==
+
==Key API functions==
 
There are two core functions:
 
There are two core functions:
 
<pre>
 
<pre>
Line 267: Line 335:
 
function callScript ($gwname, $params, $in, &$out, &$errors)
 
function callScript ($gwname, $params, $in, &$out, &$errors)
 
</pre>
 
</pre>
 
  
 
== Setting up queryTerminal function ==
 
== Setting up queryTerminal function ==
 
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
 
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.
 
It takes care of the communication protocol, connection properties and credentials for each object_id.
 
It takes care of the communication protocol, connection properties and credentials for each object_id.
To do so, it must be setted up properly. It calls user-defined callback function '''terminal_settings''' to  
+
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to  
 
collect the parameters. This function is responsible for overriding of connection properties based on  
 
collect the parameters. This function is responsible for overriding of connection properties based on  
 
local policy. Most of the re-definable parameters have reasonable default values, but username and
 
local policy. Most of the re-definable parameters have reasonable default values, but username and

Latest revision as of 13:47, 23 July 2021

What are RackTables gateways

RackTables is a PHP web application. Gateways are special executables residing on the same web-server, but not belonging to RackTables. The executables may be command-line scripts written in PHP, Perl, Python or any other language, or even binary files. Although PHP itself allows execution of arbitrary external commands, RackTables API provides helper functions to make such interaction ordered and convenient.

RackTables has 3 gateways out of the box: netcat, telnet and ssh. All of these are remote terminal clients providing the same interface: they take input commands from standard input, execute them on remote device and bring the output to standard output. Connection errors are reported to standard error stream and through exit code. The difference between telnet and netcat clients is that telnet supports telnet protocol escape sequences and can wait for previous command execution to end before pushing the next one. Netcat, on the other hand, streams all commands to TCP socket and closes its write end. Then it waits for remote device to close its write end and finishes. Not all devices support this mode, but at least Cisco IOS 12 devices do.

RackTables has unified API function to work with these clients: queryTerminal. It decides which gateway and which connection parameters to use based on user-defined callback function results.

List of device breeds

In RackTables source code a breed stands for a distinguished type of a managed device. There are currently the following breeds implemented:

Breed Code Description
air12 Cisco Aironet IOS release 12.x
dlink D-Link, unknown release
eos4 Arista EOS release 4.x
fdry5 Foundry Networks IronWare release 5.x
ftos8 Force10 FTOS release 8.x
hpprocurveN1178 HP N.11.78
ios12 Cisco Catalyst IOS release 12.x
ios15 Cisco IOS release 15.x
iosxr4 Cisco XR IOS release 4.2
jun10 Juniper JunOS releases 10, 11 and 12
linux generic Linux
nxos4 Cisco Nexus NX-OS releases 4.x, 5.x and 6.x
ros11 Marvell ROS release 1.1
ucs Cisco UCS
vrp53 Huawei VRP release 5.3
vrp55 Huawei VRP releases 5.5 and 5.7
vrp85 Huawei VRP release 8.5
xos12 Extreme Networks XOS release 12

List of device commands

Command Code Description
xlatepushq Translates a given array of breed-independent operations into a multiline string with breed-specific commands.
get8021q Returns the 802.1Q configuration of the device as a list of arrays.
getallconf Returns the device's current configuration as a string in native plain-text format (multiline).
getcdpstatus Returns the list of CDP neighbors as an array.
getlldpstatus Returns the list of LLDP neighbors as an array.
getmaclist Returns the MAC address table (for all ports) as an array.
getportmaclist Returns the MAC address table (for a specific port only) as an array.
getportstatus Returns the full list of network interfaces as an array.
getinventory Returns a list of hardware components as an array.

Implementation matrix

xlatepushq get8021q getallconf getcdpstatus getlldpstatus getmaclist getportmaclist getportstatus getinventory
air12
dlink
eos4
fdry5
ftos8
hpprocurveN1178
ios12
ios15
iosxr4
jun10
linux
nxos4
ros11
ucs
vrp53
vrp55
vrp85
xos12

File layout

The gateways part consist of two file sets:

  • PHP files stored in wwwroot/inc/ dir:
    deviceconfig.php
    Contains most vendor-specific functions translating from plain text to RackTables PHP arrays/strings and back. Support for new breeds typically requires adding functions to this file.
    remote.php
    The current 0.20.x gateways API. This file normally requires no changes.
    gateways.php
    Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x. It was removed in 0.20.2
  • CLI tools stored in gateways/ dir:
    netcat ssh sshnokey telnet ucssdk
    CLI-mode clients providing a particular communication protocol.
    gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/
    Old-style CLI tools. Removed in 0.20.2.

Key API functions

There are two core functions:

function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
function callScript ($gwname, $params, $in, &$out, &$errors)

Setting up queryTerminal function

Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function. It takes care of the communication protocol, connection properties and credentials for each object_id. To do so, it must be set up properly. It calls the user-defined callback function terminal_settings to collect the parameters. This function is responsible for overriding of connection properties based on local policy. Most of the re-definable parameters have reasonable default values, but username and password must be specifyed in any case.

Here is a full schema of $params array (with default values) which could be changed in terminal_settings:

	$params = array (array
	(
		'hostname' => $endpoints[0], // either hostname or IP
		'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'
		'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'
		'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables
		'username' => NULL,
		'password' => NULL,
		'timeout' => 15,
		'connect_timeout' => 2,
		'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'
		'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u
		'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.
	));

Typical implementation of this user-defined callback looks like this:

function terminal_settings ($cell, $params)
{
        // servers and Juniper routers use ssh, other - telnet
        if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))
        {
                $params[0]['protocol'] = 'ssh';
                $params[0]['proto'] = '4';
                $params[0]['sudo_user'] = 'racktables';
                $params[0]['connect_timeout'] = 5;
        }
        else
        {
                $params[0]['protocol'] = 'telnet';
                $params[0]['username'] = 'username';
                $params[0]['password'] = 'password';
                $params[0]['timeout'] = 30;
        }
}

You can put your definition of terminal_settings function into your secret.php file.