From RackTables Wiki
Revision as of 08:52, 9 June 2013 by Andriyanov (talk | contribs)
Jump to navigation Jump to search

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:

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
ios12 Cisco Catalyst IOS release 12.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
xos12 Extreme Networks XOS release 12

List of device commands

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 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 getportstatus getinventory

File layout

The gateways part consist of two file sets:

  • PHP files stored in wwwroot/inc/ dir:
    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.
    The current 0.20.x gateways API. This file normally requires no changes.
    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 funcrions

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 setted up properly. It calls 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;
                $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.