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:

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.