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.

What is device "breed"

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)
• 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)
• nxos4 (Cisco Nexus NX-OS releases 4.x, 5.x and 6.x)
• ros11 (Marvell ROS release 1.1)
• vrp53 (Huawei VRP release 5.3)
• vrp55 (Huawei VRP releases 5.5 and 5.7)

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.