Gateways

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

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.

Key source code files

There are three main files involved in operation of RackTables gateways infrastructure:

gateways.php

Formerly the main source code of the old API of RackTables 0.16.x to 0.19.x, now contains mostly legacy functions and will be dismissed in future releases. New functions should not be added to this file. Its purpose is mostly containing $breedfunc and detectDeviceBreed().

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.

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;
        }
        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.