https://wiki.racktables.org/api.php?action=feedcontributions&user=Adoom42&feedformat=atomRackTables Wiki - User contributions [en]2024-03-28T23:48:39ZUser contributionsMediaWiki 1.34.1https://wiki.racktables.org/index.php?title=Plugins&diff=857Plugins2017-10-02T16:46:35Z<p>Adoom42: </p>
<hr />
<div>== Overview ==<br />
Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.<br />
<br />
=== States ===<br />
A plugin may be in one of three states.<br />
* Not installed - it exists in the plugins directory, but hasn't been installed yet<br />
* Enabled - it has been installed and is active<br />
* Disabled - it has been installed and was subsequently disabled<br />
<br />
=== Administration ===<br />
To install a plugin, first copy it to the "plugins" directory. Then visit the Configuration -> Plugins page and click the Edit tab. The new plugin should be listed with a state of "Not installed". Click the Install icon.<br />
<br />
To upgrade a plugin, first backup the appropriate "plugins" sub-directory. To be safe, it's also a good idea to backup your entire database. Afterwards, copy over the new version into the "plugins" directory. When you visit the Edit tab of the Configuration -> Plugins page, you should see a variance in the Code Version and DB Version columns. Click the Upgrade icon.<br />
<br />
== Writing a Plugin ==<br />
The old procedure involves placing a PHP file in the "plugins" directory of your RackTables installation. That method has limited functionality and may be deprecated at a later date.<br />
<br />
A new plugin architecture was introduced in version 0.21.0. It includes the ability to install, uninstall, enable and disable plugins from the web interface. It is assumed that each plugin resides in its own directory within the main "plugins" directory, and that each plugin contains a "plugin.php" file which includes certain functions. The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.<br />
<br />
=== Files ===<br />
Each plugin is expected to contain certain files. While the only required file is "plugin.php", it is recommended that you include all mentioned files, especially if you intend to publish it for others.<br />
<br />
* README - Provide a general description. If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.<br />
* ChangeLog - Document changes made to each revision.<br />
* LICENSE<br />
<br />
=== Functions ===<br />
{| class="wikitable"<br />
!Name<br />
!Returns<br />
!Description<br />
|-<br />
|plugin_PLUGINNAME_info<br />
|array<br />
|Array contains 'name', 'longname', 'version' & 'home_url'<br />
|-<br />
|plugin_PLUGINNAME_init<br />
|void<br />
|Initialize the plugin. Register pages, tabs, triggers, handlers, etc.<br />
|-<br />
|plugin_PLUGINNAME_install<br />
|boolean<br />
|Make any necessary modifications (create tables, create Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_uninstall<br />
|boolean<br />
|Make any necessary modifications (drop tables, delete Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_upgrade<br />
|boolean<br />
|Make any necessary modifications (alter tables, modify Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_HOOKNAME<br />
|varies<br />
|Run when called by a system-level function (described below in the Hooks section)<br />
|}<br />
<br />
=== Hooks ===<br />
These are used in cases where custom functions defined by a plugin should be called at specific times.<br />
<br />
Examples:<br />
* When resetting or deleting an object<br />
* Resetting the Config settings (Configuration -> User interface)<br />
* Viewing the Data Integrity report<br />
<br />
Hooks are already supported in some functions, such as commitResetObject(). If you need it supported by another function, create a GitHub pull request and it will probably be accepted.<br />
<br />
=== Upgrades ===<br />
The plugin_PLUGINNAME_upgrade function is mandatory. If this is the first version, or if no upgrade steps are required, simply have the function return TRUE.<br />
<br />
There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information. These transitions should be handled by the upgrade function.<br />
<br />
Example modeled after the core RackTables upgrader:<br />
<br />
<pre><br />
function plugin_myplugin_upgrade ()<br />
{<br />
$db_info = getPlugin ('myplugin');<br />
$v1 = $db_info['db_version'];<br />
$code_info = plugin_plugin_info ();<br />
$v2 = $code_info['version'];<br />
<br />
if ($v1 == $v2)<br />
throw new RackTablesError ('Versions are identical', RackTablesError::INTERNAL);<br />
<br />
// find the upgrade path to be taken<br />
$versionhistory = array<br />
(<br />
'1.0',<br />
'2.0',<br />
'3.0'<br />
);<br />
$skip = TRUE;<br />
$path = NULL;<br />
foreach ($versionhistory as $v)<br />
{<br />
if ($skip and $v == $v1)<br />
{<br />
$skip = FALSE;<br />
$path = array();<br />
continue;<br />
}<br />
if ($skip)<br />
continue;<br />
$path[] = $v;<br />
if ($v == $v2)<br />
break;<br />
}<br />
if ($path === NULL or ! count ($path))<br />
throw new RackTablesError ('Unable to determine upgrade path', RackTablesError::INTERNAL);<br />
<br />
// build the list of queries to execute<br />
$queries = array ();<br />
foreach ($path as $batchid)<br />
{<br />
switch ($batchid)<br />
{<br />
case '2.0':<br />
// perform some upgrade step here<br />
$queries[] = "UPDATE Plugin SET version = '2.0' WHERE name = 'myplugin'";<br />
break;<br />
case '3.0':<br />
// perform some upgrade step here<br />
$queries[] = "UPDATE Plugin SET version = '3.0' WHERE name = 'myplugin'";<br />
break;<br />
default:<br />
throw new RackTablesError ("Preparing to upgrade to $batchid failed", RackTablesError::INTERNAL);<br />
}<br />
}<br />
<br />
// execute the queries<br />
global $dbxlink;<br />
foreach ($queries as $q)<br />
{<br />
try<br />
{<br />
$result = $dbxlink->query ($q);<br />
}<br />
catch (PDOException $e)<br />
{<br />
$errorInfo = $dbxlink->errorInfo();<br />
throw new RackTablesError ("Query: ${errorInfo[2]}", RackTablesError::INTERNAL);<br />
}<br />
}<br />
}<br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=Plugins&diff=855Plugins2017-10-02T16:44:21Z<p>Adoom42: </p>
<hr />
<div>== Overview ==<br />
Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.<br />
<br />
=== States ===<br />
A plugin may be in one of three states.<br />
* Not installed - it exists in the plugins directory, but hasn't been installed yet<br />
* Enabled - it has been installed and is active<br />
* Disabled - it has been installed and was subsequently disabled<br />
<br />
=== Administration ===<br />
To install a plugin, first copy it to the "plugins" directory. Then visit the Configuration -> Plugins page and click the Edit tab. The new plugin should be listed with a state of "Not installed". Click the Install icon.<br />
<br />
To upgrade a plugin, first backup the appropriate "plugins" sub-directory. To be safe, it's also a good idea to backup your entire database. Afterwards, copy over the new version into the "plugins" directory. When you visit the Edit tab of the Configuration -> Plugins page, you should see a variance in the Code Version and DB Version columns. Click the Upgrade icon.<br />
<br />
== Writing a Plugin ==<br />
The old procedure involves placing a PHP file in the "plugins" directory of your RackTables installation. That method has limited functionality and may be deprecated at a later date.<br />
<br />
A new plugin architecture was introduced in version 0.21.0. It includes the ability to install, uninstall, enable and disable plugins from the web interface. It is assumed that each plugin resides in its own directory within the main "plugins" directory, and that each plugin contains a "plugin.php" file which includes certain functions. The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.<br />
<br />
=== Files ===<br />
Each plugin is expected to contain certain files. While the only required file is "plugin.php", it is recommended that you include all mentioned files, especially if you intend to publish it for others.<br />
<br />
* README - Provide a general description. If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.<br />
* ChangeLog - Document changes made to each revision.<br />
* LICENSE<br />
<br />
=== Functions ===<br />
{| class="wikitable"<br />
!Name<br />
!Returns<br />
!Description<br />
|-<br />
|plugin_PLUGINNAME_info<br />
|array<br />
|Array contains 'name', 'longname', 'version' & 'home_url'<br />
|-<br />
|plugin_PLUGINNAME_init<br />
|void<br />
|Initialize the plugin. Register pages, tabs, triggers, handlers, etc.<br />
|-<br />
|plugin_PLUGINNAME_install<br />
|boolean<br />
|Make any necessary modifications (create tables, create Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_uninstall<br />
|boolean<br />
|Make any necessary modifications (drop tables, delete Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_upgrade<br />
|boolean<br />
|Make any necessary modifications (alter tables, modify Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_HOOKNAME<br />
|varies<br />
|Run when called by a system-level function (described below in the Hooks section)<br />
|}<br />
<br />
=== Hooks ===<br />
There are used in cases where custom functions defined by a plugin should be called at specific times.<br />
<br />
Examples:<br />
* When resetting or deleting an object<br />
* Resetting the Config settings (Configuration -> User interface)<br />
* Viewing the Data Integrity report<br />
<br />
Hooks are already supported in some functions, such as commitResetObject(). If you need it supported by another function, create a GitHub pull request and it will probably be accepted.<br />
<br />
=== Upgrades ===<br />
The plugin_PLUGINNAME_upgrade function is mandatory. If this is the first version, or if no upgrade steps are required, simply have the function return TRUE.<br />
<br />
There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information. These transitions should be handled by the upgrade function.<br />
<br />
Example modeled after the core RackTables upgrader:<br />
<br />
<pre><br />
function plugin_myplugin_upgrade ()<br />
{<br />
$db_info = getPlugin ('myplugin');<br />
$v1 = $db_info['db_version'];<br />
$code_info = plugin_plugin_info ();<br />
$v2 = $code_info['version'];<br />
<br />
if ($v1 == $v2)<br />
throw new RackTablesError ('Versions are identical', RackTablesError::INTERNAL);<br />
<br />
// find the upgrade path to be taken<br />
$versionhistory = array<br />
(<br />
'1.0',<br />
'2.0',<br />
'3.0'<br />
);<br />
$skip = TRUE;<br />
$path = NULL;<br />
foreach ($versionhistory as $v)<br />
{<br />
if ($skip and $v == $v1)<br />
{<br />
$skip = FALSE;<br />
$path = array();<br />
continue;<br />
}<br />
if ($skip)<br />
continue;<br />
$path[] = $v;<br />
if ($v == $v2)<br />
break;<br />
}<br />
if ($path === NULL or ! count ($path))<br />
throw new RackTablesError ('Unable to determine upgrade path', RackTablesError::INTERNAL);<br />
<br />
// build the list of queries to execute<br />
$queries = array ();<br />
foreach ($path as $batchid)<br />
{<br />
switch ($batchid)<br />
{<br />
case '2.0':<br />
// perform some upgrade step here<br />
$queries[] = "UPDATE Plugin SET version = '2.0' WHERE name = 'myplugin'";<br />
break;<br />
case '3.0':<br />
// perform some upgrade step here<br />
$queries[] = "UPDATE Plugin SET version = '3.0' WHERE name = 'myplugin'";<br />
break;<br />
default:<br />
throw new RackTablesError ("Preparing to upgrade to $batchid failed", RackTablesError::INTERNAL);<br />
}<br />
}<br />
<br />
// execute the queries<br />
global $dbxlink;<br />
foreach ($queries as $q)<br />
{<br />
try<br />
{<br />
$result = $dbxlink->query ($q);<br />
}<br />
catch (PDOException $e)<br />
{<br />
$errorInfo = $dbxlink->errorInfo();<br />
throw new RackTablesError ("Query: ${errorInfo[2]}", RackTablesError::INTERNAL);<br />
}<br />
}<br />
}<br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=NewRelease&diff=751NewRelease2016-01-13T23:59:35Z<p>Adoom42: MySQL user should be named 'racktables_user'</p>
<hr />
<div>== pre-release checklist ==<br />
=== part 1 ===<br />
First make sure, that all necessary changes are already committed into the repository:<br />
<ul><br />
<br />
<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:<br />
<pre><br />
git status<br />
</pre><br />
<li>If the new release has any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li><br />
<br />
<li>Update <tt>ChangeLog</tt> file to have the current date on the new version line.</li><br />
<br />
<li>Make sure that <tt>upgrade.php</tt> has new version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li><br />
<br />
<li>Bump up CODE_VERSION in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li><br />
<br />
<li>Produce a commit with all changes pending thus far:<br />
<pre><br />
git status<br />
git add ChangeLog<br />
[...]<br />
git add wwwroot/inc/config.php<br />
git commit<br />
</pre><br />
</li><br />
<br />
<li>Check the source code out from the same branch to a '''clean location''' to test it.<br />
<pre><br />
git clone git@github.com:RackTables/racktables.git<br />
cd racktables<br />
git checkout master # or maintenance<br />
</pre></li><br />
<br />
<li>The application must be able to install itself with own installer. Once this is found working, dump the database:<br />
<pre><br />
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql<br />
</pre></li><br />
<br />
<li>Demo data must be loadable without any errors:<br />
<pre><br />
mysql racktables_db < scripts/init-sample-racks.sql<br />
</pre></li><br />
<br />
<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.<br />
<pre><br />
# reload using the previous release<br />
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db<br />
# (make through upgrade.php)<br />
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql<br />
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql<br />
</pre></li><br />
<br />
=== part 2 (unit testing) ===<br />
<li>Setup a fresh database and grant access to the 'racktables_user' user. This will be used to create a sample data file that unit tests can utilize.</li><br />
<pre><br />
DROP DATABASE IF EXISTS racktables_unittest;<br />
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;<br />
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';<br />
</pre><br />
<br />
<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li><br />
<br />
<li>Load the sample data.</li><br />
<pre>mysql -u racktables_user -p racktables_unittest < scripts/init-sample-racks.sql</pre><br />
<br />
<li>Export the database to the tests/data dir.</li><br />
<pre>mysqldump --skip-comments -u racktables_user -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre><br />
<br />
<li>Run the unit tests. Fix any failures.</li><br />
<pre><br />
cd tests<br />
phpunit<br />
</pre><br />
<br />
=== part 3 (finalization) ===<br />
<li>Test the source by hand as much as you find possible.</li><br />
<br />
<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li><br />
<br />
<li>Do not proceed further until everything is fixed consistently.</li><br />
</ul><br />
<br />
== the release itself ==<br />
<pre><br />
git tag RackTables-X.Y.z<br />
git push origin RackTables-X.Y.z<br />
</pre><br />
<br />
== rolling out ==<br />
=== producing and publishing deliverables ===<br />
* Delete the 'tests' directory. It is several megabytes in size and will only be used by developers. Users can obtain the tests using git, if desired.<br />
* Make two archives:<br />
<pre><br />
export TAG='RackTables-X.Y.z'<br />
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG<br />
git archive --prefix=$TAG/ -o $TAG.zip $TAG<br />
</pre><br />
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/apps/trac/sourceforge/wiki/Release%20files%20for%20download other means]).<br />
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded tar.gz as "current".<br />
** Open properties form (round "i" sign) of the previous release tar.gz.<br />
** Unset all "default download for" checkboxes.<br />
** Unset "download button" text.<br />
** Save.<br />
** Open properties form (round "i" sign) of the previous release zip.<br />
** Unset Windows "default download for" checkbox.<br />
** Unset "download button" text.<br />
** Save.<br />
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.<br />
** Set "download button" text to "latest stable".<br />
** Save.<br />
** In the latest zipfile properties form, set Windows "default download for" checkbox.<br />
** Save.<br />
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).<br />
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section, open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).<br />
<br />
=== updating Mantis ===<br />
* In MantisBT mark version as released (Manage, Manage Projects, [http://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions).<br />
=== updating the main web-site ===<br />
* Log into SF shell service:<br />
<pre><br />
$ cat ~/.ssh/config <br />
Host shell.sourceforge.net<br />
User YOUR_SF_USERNAME,racktables<br />
$ ssh -t shell.sourceforge.net create<br />
# upon logging in update $lastrelease<br />
$ vim /home/project-web/racktables/htdocs/header.php<br />
# test the "download" link at racktables.org to work<br />
</pre><br />
=== updating other news feeds ===<br />
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).<br />
* Update IRC channel topic<br />
<br />
=== updating demo ===<br />
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].<br />
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.<br />
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).<br />
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt><br />
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].<br />
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.<br />
** <tt>git commit; git push</tt><br />
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:<br />
<pre><br />
cd ~/racktables<br />
git pull<br />
git checkout RackTables-0.20.3<br />
ln -s ~/racktables ~/RackTables-0.20.3<br />
# secret.php is already in wwwroot/inc/<br />
# local.php is already in plugins/<br />
cd ~/racktables-contribs/<br />
git pull<br />
cd<br />
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo<br />
crontab -e<br />
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php<br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=Plugins&diff=745Plugins2015-12-29T00:32:24Z<p>Adoom42: Created page with "== Overview == Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktable..."</p>
<hr />
<div>== Overview ==<br />
Plugins provide the ability to add functionality to RackTables and, in some cases, override existing behavior. See the [https://github.com/RackTables/racktables-contribs racktables-contribs] repository for user-submitted plugins.<br />
<br />
Note that this guide details features that may or may not be included in a future release.<br />
<br />
=== States ===<br />
A plugin may be in one of three states.<br />
* Not installed - it exists in the plugins directory, but hasn't been installed yet<br />
* Enabled - it has been installed and is active<br />
* Disabled - it has been installed and was subsequently disabled<br />
<br />
=== Administration ===<br />
To install a plugin, first copy it to the "plugins" directory. Then visit the Configuration -> Plugins page and click the Edit tab. The new plugin should be listed with a state of "Not installed". Click the Install icon.<br />
<br />
To upgrade a plugin, first backup the appropriate "plugins" sub-directory. To be safe, it's also a good idea to backup your entire database. Afterwards, copy over the new version into the "plugins" directory. When you visit the Edit tab of the Configuration -> Plugins page, you should see a variance in the Code Version and DB Version columns. Click the Upgrade icon.<br />
<br />
== Writing a Plugin ==<br />
The old procedure involves placing a PHP file in the "plugins" directory of your RackTables installation. That method has limited functionality and may be deprecated at a later date.<br />
<br />
A new plugin architecture was introduced in version 0.20.11. It includes the ability to install, uninstall, enable and disable plugins from the web interface. It is assumed that each plugin resides in its own directory within the main "plugins" directory, and that each plugin contains a "plugin.php" file which includes certain functions. The design was inspired by [http://docs.cacti.net/plugins Cacti's] plugin architecture.<br />
<br />
=== Files ===<br />
Each plugin is expected to contain certain files. While the only required file is "plugin.php", it is recommended that you include all mentioned files, especially if you intend to publish it for others.<br />
<br />
* README - Provide a general description. If you expect the plugin to be accepted into the racktables-contribs repo, use the [https://help.github.com/articles/github-flavored-markdown/ Markdown] format.<br />
* ChangeLog - Document changes made to each revision.<br />
* LICENSE<br />
<br />
=== Functions ===<br />
{| class="wikitable"<br />
!Name<br />
!Returns<br />
!Description<br />
|-<br />
|plugin_PLUGINNAME_info<br />
|array<br />
|Array contains 'name', 'longname', 'version' & 'home_url'<br />
|-<br />
|plugin_PLUGINNAME_init<br />
|void<br />
|Initialize the plugin. Register pages, tabs, triggers, handlers, etc.<br />
|-<br />
|plugin_PLUGINNAME_install<br />
|boolean<br />
|Make any necessary modifications (create tables, create Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_uninstall<br />
|boolean<br />
|Make any necessary modifications (drop tables, delete Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_upgrade<br />
|boolean<br />
|Make any necessary modifications (alter tables, modify Config settings, etc.)<br />
|-<br />
|plugin_PLUGINNAME_HOOKNAME<br />
|varies<br />
|Run when called by a system-level function (described below in the Hooks section)<br />
|}<br />
<br />
=== Hooks ===<br />
There are used in cases where custom functions defined by a plugin should be called at specific times.<br />
<br />
Examples:<br />
* When resetting or deleting an object<br />
* Resetting the Config settings (Configuration -> User interface)<br />
* Viewing the Data Integrity report<br />
<br />
Hooks are already supported in some functions, such as commitResetObject(). If you need it supported by another function, create a GitHub pull request and it will probably be accepted.<br />
<br />
=== Upgrades ===<br />
The plugin_PLUGINNAME_upgrade function is mandatory. If this is the first version, or if no upgrade steps are required, simply have the function return TRUE.<br />
<br />
There are many cases where upgrades involve adding/modifying/deleting tables, Config settings or other pieces of information. These transitions should be handled by the upgrade function.<br />
<br />
Example modeled after the core RackTables upgrader:<br />
<br />
<pre><br />
function plugin_myplugin_upgrade ()<br />
{<br />
$db_info = getPlugin ('myplugin');<br />
$v1 = $db_info['db_version'];<br />
$code_info = plugin_plugin_info ();<br />
$v2 = $code_info['version'];<br />
<br />
if ($v1 == $v2)<br />
throw new RackTablesError ('Versions are identical', RackTablesError::INTERNAL);<br />
<br />
// find the upgrade path to be taken<br />
$versionhistory = array<br />
(<br />
'1.0',<br />
'2.0',<br />
'3.0'<br />
);<br />
$skip = TRUE;<br />
$path = NULL;<br />
foreach ($versionhistory as $v)<br />
{<br />
if ($skip and $v == $v1)<br />
{<br />
$skip = FALSE;<br />
$path = array();<br />
continue;<br />
}<br />
if ($skip)<br />
continue;<br />
$path[] = $v;<br />
if ($v == $v2)<br />
break;<br />
}<br />
if ($path === NULL or ! count ($path))<br />
throw new RackTablesError ('Unable to determine upgrade path', RackTablesError::INTERNAL);<br />
<br />
// build the list of queries to execute<br />
$queries = array ();<br />
foreach ($path as $batchid)<br />
{<br />
switch ($batchid)<br />
{<br />
case '2.0':<br />
// perform some upgrade step here<br />
$queries[] = "UPDATE Plugin SET version = '2.0' WHERE name = 'myplugin'";<br />
break;<br />
case '3.0':<br />
// perform some upgrade step here<br />
$queries[] = "UPDATE Plugin SET version = '3.0' WHERE name = 'myplugin'";<br />
break;<br />
default:<br />
throw new RackTablesError ("Preparing to upgrade to $batchid failed", RackTablesError::INTERNAL);<br />
}<br />
}<br />
<br />
// execute the queries<br />
global $dbxlink;<br />
foreach ($queries as $q)<br />
{<br />
try<br />
{<br />
$result = $dbxlink->query ($q);<br />
}<br />
catch (PDOException $e)<br />
{<br />
$errorInfo = $dbxlink->errorInfo();<br />
throw new RackTablesError ("Query: ${errorInfo[2]}", RackTablesError::INTERNAL);<br />
}<br />
}<br />
}<br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=NewRelease&diff=741NewRelease2015-09-11T18:55:47Z<p>Adoom42: added unit testing instructions</p>
<hr />
<div>== pre-release checklist ==<br />
=== part 1 ===<br />
First make sure, that all necessary changes are already committed into the repository:<br />
<ul><br />
<br />
<li>Make sure you have the right branch checked out and that no pending changes are in the working copy:<br />
<pre><br />
git status<br />
</pre><br />
<li>If the new release has any release notes, make sure these appear both in <tt>wwwroot/inc/upgrade.php</tt> and in <tt>README</tt>.</li><br />
<br />
<li>Update <tt>ChangeLog</tt> file to have the current date on the new version line.</li><br />
<br />
<li>Make sure that <tt>upgrade.php</tt> has new version listed in <tt>$versionhistory</tt> and <tt>getUpgradeBatch()</tt>. It is normal to accumulate updates in <tt>getUpgradeBatch()</tt> long before the release, this way on the release day you will have nothing to do in <tt>upgrade.php</tt>. But if you had no changes to DB since the last release, you are likely to see there changes missing. Just make sure the new version is in both places anyway.</li><br />
<br />
<li>Bump up CODE_VERSION in <tt>wwwroot/inc/config.php</tt>. DON'T do this unless you really intend to make a release right now.</li><br />
<br />
<li>Produce a commit with all changes pending thus far:<br />
<pre><br />
git status<br />
git add ChangeLog<br />
[...]<br />
git add wwwroot/inc/config.php<br />
git commit<br />
</pre><br />
</li><br />
<br />
<li>Check the source code out from the same branch to a '''clean location''' to test it.<br />
<pre><br />
git clone git@github.com:RackTables/racktables.git<br />
cd racktables<br />
git checkout master # or maintenance<br />
</pre></li><br />
<br />
<li>The application must be able to install itself with own installer. Once this is found working, dump the database:<br />
<pre><br />
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql<br />
</pre></li><br />
<br />
<li>Demo data must be loadable without any errors:<br />
<pre><br />
mysql racktables_db < scripts/init-sample-racks.sql<br />
</pre></li><br />
<br />
<li>The release being tested must detect and upgrade a database from the previous release(s) correctly. Load the database with one of the previous releases data, then upgrade it with the current upgrader, then dump the DB. Now compare to the previous dump, there must be no meaningful differences.<br />
<pre><br />
# reload using the previous release<br />
/path/to/racktables-contribs/demo.racktables.org/demoreload.sh X.Y.z racktables_db<br />
# (make through upgrade.php)<br />
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql<br />
diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql<br />
</pre></li><br />
<br />
=== part 2 (unit testing) ===<br />
<li>Setup a fresh database and grant access to the 'racktables' user. This will be used to create a sample data file that unit tests can utilize.</li><br />
<pre><br />
DROP DATABASE IF EXISTS racktables_unittest;<br />
CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;<br />
GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';<br />
</pre><br />
<br />
<li>Use the web interface to complete the installation. When prompted to set the admin password, enter 'admin'.</li><br />
<br />
<li>Load the sample data.</li><br />
<pre>mysql -u racktables -p racktables_unittest < scripts/init-sample-racks.sql</pre><br />
<br />
<li>Export the database to the tests/data dir.</li><br />
<pre>mysqldump --skip-comments -u racktables -p racktables_unittest > tests/data/$CODE_VERSION.sql</pre><br />
<br />
<li>Run the unit tests. Fix any failures.</li><br />
<pre><br />
cd tests<br />
phpunit<br />
</pre><br />
<br />
=== part 3 (finalization) ===<br />
<li>Test the source by hand as much as you find possible.</li><br />
<br />
<li>Look into the error log of the server you used for the tests. There shouldn't be any error/warning messages.</li><br />
<br />
<li>Do not proceed further until everything is fixed consistently.</li><br />
</ul><br />
<br />
== the release itself ==<br />
<pre><br />
git tag RackTables-X.Y.z<br />
git push origin RackTables-X.Y.z<br />
</pre><br />
<br />
== rolling out ==<br />
=== producing and publishing deliverables ===<br />
* Delete the 'tests' directory. It is several megabytes in size and will only be used by developers. Users can obtain the tests using git, if desired.<br />
* Make two archives:<br />
<pre><br />
export TAG='RackTables-X.Y.z'<br />
git archive --prefix=$TAG/ -o $TAG.tar.gz $TAG<br />
git archive --prefix=$TAG/ -o $TAG.zip $TAG<br />
</pre><br />
* Upload the tarball and zipfile to SF FRS ([https://sourceforge.net/projects/racktables/files/ from browser] or by [https://sourceforge.net/apps/trac/sourceforge/wiki/Release%20files%20for%20download other means]).<br />
* Open [https://sourceforge.net/projects/racktables/files files section] and set the newly uploaded tar.gz as "current".<br />
** Open properties form (round "i" sign) of the previous release tar.gz.<br />
** Unset all "default download for" checkboxes.<br />
** Unset "download button" text.<br />
** Save.<br />
** Open properties form (round "i" sign) of the previous release zip.<br />
** Unset Windows "default download for" checkbox.<br />
** Unset "download button" text.<br />
** Save.<br />
** In the latest tarball properties form, set all "default download for" checkboxes except Windows.<br />
** Set "download button" text to "latest stable".<br />
** Save.<br />
** In the latest zipfile properties form, set Windows "default download for" checkbox.<br />
** Save.<br />
** Hover the big green "download" button and watch the mouse hint featuring the right version number (sometimes it takes several minutes to see the update).<br />
** '''Tip:''' to update the banner text below the file list of the SF's "Files" section, open a terminal connection to SF shell and edit the file <tt>/home/frs/project/racktables/README.md</tt> (once done, let the SF 5-10 minutes to start using the updated revision).<br />
<br />
=== updating Mantis ===<br />
* In MantisBT mark version as released (Manage, Manage Projects, [http://bugs.racktables.org/manage_proj_edit_page.php?project_id=1 RackTables], Versions).<br />
=== updating the main web-site ===<br />
* Log into SF shell service:<br />
<pre><br />
$ cat ~/.ssh/config <br />
Host shell.sourceforge.net<br />
User YOUR_SF_USERNAME,racktables<br />
$ ssh -t shell.sourceforge.net create<br />
# upon logging in update $lastrelease<br />
$ vim /home/project-web/racktables/htdocs/header.php<br />
# test the "download" link at racktables.org to work<br />
</pre><br />
=== updating other news feeds ===<br />
* Send a letter to the racktables-users list (even more so after Freshmeat/Freecode is gone).<br />
* Update IRC channel topic<br />
<br />
=== updating demo ===<br />
* Produce a helper SQL file for the current release in [https://github.com/RackTables/racktables-contribs racktables-contribs].<br />
** Copy the previous <tt>init-full-X.Y.z.sql</tt> to current <tt>init-full-X.Y.z.sql</tt> and <tt>git add</tt> the new file.<br />
** Take a clean RackTables instance of the current release (either use demoreload on the previous release or install manually).<br />
** Make an SQL dump of this new installation like this: <tt>mysqldump --extended-insert=FALSE --order-by-primary racktables_db > init-full-X.Y.z.sql</tt><br />
** Edit permissions like [https://github.com/RackTables/racktables-contribs/commit/0354001ce16e937cfc5ae555fe73dc3c351a6556 this].<br />
** <tt>git add -i</tt> the new file again (note interactive add). Use patch mode to add relevant chunks. Quit.<br />
** <tt>git commit; git push</tt><br />
* Update demo.racktables.org to the current release (<tt>$demorelease</tt> will need an update). Below is a sample CLI session of updating the demo to 0.20.3:<br />
<pre><br />
cd ~/racktables<br />
git pull<br />
git checkout RackTables-0.20.3<br />
ln -s ~/racktables ~/RackTables-0.20.3<br />
# secret.php is already in wwwroot/inc/<br />
# local.php is already in plugins/<br />
cd ~/racktables-contribs/<br />
git pull<br />
cd<br />
~/racktables-contribs/demo.racktables.org/demoreload.sh 0.20.3 rackdemo<br />
crontab -e<br />
# ../../racktables/wwwroot/index.php is already linked as www/demo/index.php<br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=RackTablesUserGuide&diff=739RackTablesUserGuide2015-06-11T02:42:14Z<p>Adoom42: /* Physical Objects */</p>
<hr />
<div>= Port and links =<br />
A port or physical interface is part of an object which you can connect a cable to. Each port can have a local name, that is how this port is visible from the OS point of view. For a Linux system that will be eth0, eth1, etc. Visible label is what is physically written on the port.<br />
<br />
Depending on the manufacturer you may observe labels as "1", "2", etc. or something else. Port type is an essential property that allows port connections to be properly arranged. It lets you know that you won't be able to connect optical and copper ports together with one cable. Some ports have an L2 address. It's helpful to populate those, as you may find it handy to find ports by L2 addresses while investigating your STP tree.<br />
<br />
Reserving a port is simply adding a comment to it, thus preventing it to be linked. A good reservation can be "Reserved for a field engineer laptop". Linking ports is creating a connection between them. That is plugging a cable to them. Only ports with compatible types can be linked. Say, RJ-45/100-Base TX can be linked to RJ-45/1000-Base TX, but can't be linked to LC/100-BASE FX. In many cases you'll need to add a bunch of ports from a switch. In this case there is a text area and a format selector. Just choose your device and format, paste the output to the textarea and click "Parse output" button. Also, you need to choose which port type is to be used, since it's not possible to guess that from the output.<br />
----<br />
<br />
= Networking =<br />
== IP subnets ==<br />
This tab manages IPv4 resources. All IPv4 addresses are grouped to subnets. Subnets make a hierarchy, which is computed and displayed automatically. An IPv4 address __can__ belong to a network. Sometimes it doesn't. There is an option ("Enable IPv4 address allocations w/o covering network") to deal with that. When it is enabled, the system refuses to assign "martian" IP addresses to objects. However, this option doesn't affect already assigned "martian" addresses.<br />
<br />
== IP addresses ==<br />
Every IP address can be either bound to an interface or free. On the other hand, it can<br />
be either reserved or not. That makes 4 possible states: bound - reserved, bound - unreserved, free - reserved<br />
free - unreserved. The first state is considered as "conflicting" and will be shown red-highlited.<br />
An IP address may have a "Name" assigned to it, which is intended to be used as a short comment.<br />
An example would be "The default GW" or "Reserved for field engineer"<br />
Binding an address to an interface is called "allocation". The interface is a rack object plus an interface name.<br />
The interface name can be the same as a physical port label on that box or something else.<br />
If you are binding it to a linux box with 2 physical ports, you might want to name interfaces as<br />
eth0, eth1, eth0:4, eth1.110, etc, whereas your physical port names will be eth1 and eth2<br />
The difference between ports and interfaces is that say a switch may have 24 ports and only 1 interface,<br />
which is accessable from any of those ports. Generally, one IP address can be bound only to one interface,<br />
otherwise it's considered as a "collision". However, there are exceptions and a tool to mark<br />
those exceptions. There is a "bond type" or "interface type", which can be either "Regular"<br />
or "Shared" or "Virtual". Shared means that 2 or more peers share the same IP address<br />
like it's done in VRRP or HSRP. Usually, there is only one box possessing it at a time<br />
but when it dies, another one will have it. Shared bonds will not conflict with each other,<br />
but will conflict with regular bindings of the same IP address. Virtual interface is<br />
an assignment that usually don't broadcast itself through the network, but will allow<br />
the OS to accept packets with that IP address sent to the box. This is widely used<br />
in loadbalancing technics where loadbalancers simply do ARP proxy; they rewrite L2 address<br />
in L2 frames with target's address and resend them back to the network. Virtual interfaces<br />
do not conflict with any other interface types. Note: do not use virtual interfaces if<br />
your loadbalancer uses NAT. There is a NAT tab for that instead.<br />
<br />
== NATv4 ==<br />
Boxes can translate their own L4 addresses to other L4 addresses on other boxes. This is called<br />
NAT. In protocol selection box you can choose 2 protocols so far, UDP and TCP. Source is one of<br />
IP addresses assigned to the box and after a colon is a box for numerical port. As a target you<br />
have to choose a target IP address and port it will be translated to. Add a decription if you like.<br />
After submitting the form you will find that if there was an object assined to the target IP address<br />
it will be shown as well. A single source IP address/port can be assigned to multiple target IP<br />
addresses/ports. That will represent an L4 loadbalancing. And vice versa, multiple sources can be<br />
translated to one target.<br />
----<br />
<br />
= Rackspace =<br />
<br />
== Rack design tab ==<br />
Rack design defines the physical layout of a rack cabinet. Most common reason to use the tab is absence of back rails, although any other design can be defined. In this tab you can change mounting atoms' state between 'free' and 'absent'. A selected checkbox means atom presence.<br />
<br />
=== Reversing Rack Numbering ===<br />
Rack numbering can be reversed through the global configuration parameter REVERSED_RACKS_LISTSRC available at Configuration->User interface. This value is a [[#RackCode|RackCode]] expression and can be a tag "{tag}" or "true" or "false" for global configuration.<br />
<br />
== Rack problems tab ==<br />
Rack problems prevent free rackspace from being used for mounting. Such rackspace is considered unusable. After the problem is gone, the atom can become free again. In this tab you can change atoms' state from free to unusable and back. A selected checkbox means a problem.<br />
----<br />
<br />
= Live PTR =<br />
First of all, an important notice has to be done about names (or "descriptions") of IP addresses. If you know about the real objects, to which addresses belong, it is recommended to create those objects and then allocate IP addresses to them. This approach will keep your dataset consistent and cross-linked. Address descriptions normally should contain supplementary, but useful information: the role or a well-known DNS name of a particular address.<br />
<br />
The feature allows matching description of each IP address of the current IP subnet with DNS PTR record, resolved online. !RackTables highlights each address accordingly to its current description and DNS data; however, it is a rough estimation if each particular description is correct or not. It is left up to the user to decide, if DNS data, as more accurate, should be imported into DB.<br />
----<br />
<br />
= SNMP Sync =<br />
It is possible to initialise switch port and system data through SNMP on freshly created objects. If the switch model is known for RackTables (either as a part of the distribution or through [[RackTablesDevelGuide#SNMP_sync|local admin magic]]) and accessible through SNMP then by using the SNMP Sync tab Racktables try to connect the switch by version1, version2c or version3 protocol, using the user provided community (and/or authentication data) for access (the community can be set in general configuration) and fills the port data, firmware version etc.<br />
<br />
The host used first looked up in the FQDN field, then if empty in the first IP adderess assigned to the object.<br />
----<br />
<br />
= Containers =<br />
Container objects were introduced in version 0.19 to support various scenarios.<br />
<br />
Similar to the port compatibility matrix, the object compatibility matrix defines valid relationships. It's located on the Configuration page.<br />
<br />
You choose an object's container using the 'Select container' link on the object's Properties tab. This link is only visible if the object type exists as a child in the object compatibility matrix.<br />
<br />
Objects may have multiple containers. This is to support unique scenarios such as a blade server which is used to host virtual machines. It could potentially have two valid containers - the blade server chassis as well as the VM cluster.<br />
<br />
If an object contains any other objects, they are listed on the Object->View page.<br />
<br />
== Physical Objects ==<br />
Object types include Network chassis and Server chassis.<br />
<br />
Common container scenarios:<br />
* Blade server chassis -> blade (server or network switch blades)<br />
* Network chassis -> blade<br />
* Shelf -> modems (or any other small objects sitting on the shelf)<br />
<br />
When mousing over the container object's name in the rackspace area, the hover displays a list of all contained objects. Only immediate children are listed, grand-children, great-grand-children, etc. are not.<br />
<br />
=== Visual Representation ===<br />
When adding a chassis HW type to the dictionary, the dimensions may be specified as follows :<br />
%L<rows>,<cols>[<layout>]%<br />
<br />
<rows> is the number of rows, <cols> is the number of columns and <layout> is an optional layout hint (either H for horizonal or V for vertical).<br />
<br />
Examples:<br />
* Cisco 6509-E (9 horizontal slots): %L9,1H%<br />
* Dell M1000e (2 rows, each with 8 vertical slots): %L2,8V%<br />
<br />
If the layout hint is not supplied, a chassis with less than 6 slots will be laid out with horizontal slot names, otherwise vertical slot names will be used.<br />
<br />
== Virtual Objects ==<br />
New object types include VM, VM Cluster, VM Resource Pool and VM Virtual Switch. Although the terminology is common to VMware environments, the object types may be used in a generic manner to support other scenarios.<br />
<br />
The VIRTUAL_OBJ_LISTSRC Config option specifies which object types are virtual. Virtual objects may not be mounted in a rack. They also lack the asset tag, barcode and label fields.<br />
<br />
A Virtual Resources link on the front page leads to a summary page detailing clusters, resource pools, hypervisors and virtual switches.<br />
<br />
The Hypervisor attribute was added and associated with Server objects. It may be set to Yes or No. When selecting a container for a VM or VM Virtual Switch, the only servers listed are those with the Hypervisor attribute set to Yes. This was done to limit the number of entries displayed in the selector pop-up window.<br />
<br />
The NATv4, RS pools, keepalived.conf and Live ports tabs are not associated with VMs. If you'd like them to be, edit the appropriate Config entries to include {$typeid_1504} which is the objtype_id of VMs.<br />
<br />
=== Example Scenarios===<br />
The object type is in parentheses.<br />
<br />
Example 1: Individual server hosting VMs<br />
<br />
* MyHypervisor (Server)<br />
** MyAppServer (VM)<br />
** MyWebServer (VM)<br />
** MyDatabaseServer (VM)<br />
<br />
Example 2: Cluster of servers hosting VMs (VMware)<br />
<br />
* MyCluster (VM Cluster)<br />
** MyHypervisor1 (Server)<br />
** MyHypervisor2 (Server)<br />
** MyHypervisor3 (Server)<br />
*** SpecialServer1 (VM)<br />
** MyDistributedSwitch (VM Virtual Switch)<br />
** DevPool (VM Resource Pool)<br />
*** DevAppServer1 (VM)<br />
*** DevAppServer2 (VM)<br />
** ProductionPool (VM Resource Pool) <br />
*** ProdAppServer1 (VM)<br />
*** ProdAppServer2 (VM)<br />
<br />
Example 3: Cluster of servers hosting VMs (XenServer)<br />
<br />
* DevPool (VM Resource Pool)<br />
** MyHypervisor1 (Server)<br />
** MyHypervisor2 (Server)<br />
** DevAppServer1 (VM)<br />
** DevAppServer2 (VM)<br />
* ProductionPool (VM Resource Pool) <br />
** MyHypervisor3 (Server)<br />
** MyHypervisor4 (Server)<br />
** ProdAppServer1 (VM)<br />
** ProdAppServer2 (VM)<br />
<br />
Example 4: VM Host + VMs + Custom Objects<br />
<br />
* MyHypervisor (Server)<br />
** MyWebServer1 (VM)<br />
*** MyCustomObject1 (Site-Foo)<br />
*** MyCustomObject1 (Site-Widget)<br />
** MyWebServer2 (VM)<br />
*** MyCustomObject1 (Site-Bar)<br />
*** MyCustomObject1 (Site-Gadget)<br />
** MyDatabaseServer (VM)<br />
----<br />
<br />
= RackCode =<br />
== Tags ==<br />
The language operates on "tags", which are plain text strings, most commonly single words much like blog post tags. A tag usually indicates a fact of belonging to certain class or group, or it may express, that certain boolean predicate is true. In !RackTables, for example, several objects can be tagged with "development" and this will show their functional assignment. Some of those objects could be tagged with "room 112" to reflect their location. Tags may have parent tags. The "room 112" tag (and perhaps some others) could have "main building" as its parent, altogether corresponding to building plan.<br />
<br />
Tags serve dual purpose: to classify entities for easier browsing or asset management and to form security context. Autotags are added into the context automatically and have dollar sign prepended to their ID. Lettercase in tag names sometimes matters: one can't create two tags, whose names only differ in case, but tag names referenced in the !RackCode are searched in the security context with case preserved. IOW, if some entity is tagged with "Dogs", a {dogs} tag test will never return true.<br />
<br />
== Tag chain ==<br />
A tag chain is just an unordered set of tags with an important extension: if a tag is present on the chain, all its parent tags, up to the topmost one, are always present too. This is true for each tag on the chain.<br />
<br />
== Predicates ==<br />
A predicate is a boolean non-recursive function, which returns either true or false. The function is referenced by its symbolic name and may use both tags and other predicates to build boolean expressions. The order of definitions matters, i.e. the predicate must be declared at the moment of a grant rule evaluation, if the rule is referencing it (this is verified automatically). A predicate can only be defined once (it cannot be redefined later).<br />
<br />
== Automatic tags ==<br />
Autotags aren't shown by default, this may be changed on the "user interface" config page. Below is the list of currently used autotags (as for 0.20.0).<br />
<br />
=== Navigation tags ===<br />
;$page_something<br />
: Always set; "something" is the name of the current page.<br />
;$tab_something<br />
: Always set; "something" is the name of the current tab.<br />
; $op_something<br />
: Only set when an operation (change request) "something" is being processed, usually immediately after hitting some kind of "submit" control. Everything happens behind the scenes, then the user is redirected to some view (often, but not always the same he arrived from) and a message log is displayed on the top of the page.<br />
;$any_op<br />
: Set, if any operation is being processes. Having this autotag in a deny rule '''should''' (not finished yet) block all modifications to the database.<br />
<br />
=== Common tags ===<br />
;$lgcn_somename<br />
: LDAP group CN. Groups are taken from user's memberOf LDAP attribute during authentication.<br />
;$untagged<br />
: Set for any entity (but except users), which __can__ have tags, but __doesn't__ have any tags set.<br />
<br />
=== Location tags ===<br />
;$any_location<br />
: set, when current focus is a location container<br />
;$locationid_000<br />
: set to the ID of the current location container<br />
<br />
=== Row tags ===<br />
;$any_row<br />
: set, when current focus is a rack row<br />
;$rowid_000<br />
: set to the ID of the current rack row<br />
<br />
=== Rack tags ===<br />
;$any_rack<br />
: set, when current focus is a rack<br />
;$rackid_000<br />
: set to the ID of the current rack<br />
<br />
=== User tags ===<br />
;$userid_000<br />
: Numerical user ID of the current user account, if the account exists in the local database.<br />
;$username_somename<br />
: Username of the current user.<br />
<br />
=== Object tags ===<br />
;$any_object<br />
: Always present in all views for objects (isn't it equivalent to $page_object?).<br />
;$id_000<br />
: When operating on a rack object (asset), this tag is always set with 000 being its database ID.<br />
;$typeid_000<br />
: Same as above, but for the ID of the type of the operated object. E. g., servers produce $typeid_4.<br />
;$cn_somename<br />
: '''If''' an object has such a common name "somename", which makes the above string be a valid tag name, this autotag is added to the context.<br />
;$attr_X_Y<br />
: Set, if object has a defined dictionary attribute. X is an attribute id and Y is a dictionary key of the value. For example, if the object has two assigned attributes: HW type(2) = Cisco Catalyst 6509-E(148), and SW type(4) = Cisco IOS 12.2(252), than two autotags are attached to this object: $attr_2_148 and $attr_4_252<br />
;$no_asset_tag<br />
: set if current object has no asset number<br />
;$unmounted<br />
: Set for objects, which have no IP addresses allocated.<br />
;$nameless<br />
: Set for objects, which __don't__ have a name, although they __should__ have one according to config ("List source: object, for which common name should be set").<br />
;$portless<br />
: Set for objects, which have zero ports.<br />
;$runs_8021Q<br />
: Set for any object, which has 802.1Q order (that is, a VLAN domain and a switch template) assigned (introduced in 0.18.0)<br />
;$8021Q_domain_000<br />
: Set for any object, which has 802.1Q order. Contains numeric ID of 802.1Q domain of the order<br />
;$8021Q_tpl_000<br />
: Set for any object, which has 802.1Q order. Contains numeric ID of 802.1Q template of the order<br />
<br />
=== IP network tags ===<br />
;$any_net<br />
: set for any IP network<br />
;$any_ip4net<br />
: set for any IPv4 network<br />
;$any_ip6net<br />
: set for any IPv6 network<br />
;$ip4netid_000<br />
: set for IPv4 networks. Contains numeric network ID<br />
;$ip6netid_000<br />
: set for IPv6 networks. Contains numeric network ID<br />
;$masklen_eq_NNN<br />
: set for any IP network. Contains network prefix length in bits<br />
;$runs_8021Q<br />
: set for IP networks which have VLANs attached to it<br />
;$vlan_NNN<br />
: set for IP networks which have VLANs attached to it. Contains numeric VLAN ID (tag number).<br />
;$spare_NNN<br />
: set for IP networks which have unallocated space in them. Contains the numeric prefix length of unallocated range. If network has multiple unallocated ranges of different sizes, multiple such tags will be assigned to it.<br />
;$aggregate<br />
: set for IP networks which have subnetworks<br />
;$ip4net-192-168-0-0-24<br />
: set for any IPv4 network. Contains network IP and prefix length separated by dashes.<br />
<br />
=== File tags ===<br />
;$any_file<br />
: Set, when current focus is a file.<br />
;$fileid_000<br />
: Holds file ID, if the current focus is a file.<br />
<br />
=== 802.1Q template tags ===<br />
;$any_vst<br />
: set for any 802.1Q template<br />
;$vstid_000<br />
: set for any 802.1Q template. Contains numeric ID of template<br />
<br />
=== Virtual service tags ===<br />
;$any_vs<br />
: set for any virtual service<br />
;$any_ipv4vs<br />
: set for any IPv4 virtual service<br />
;$any_ipv6vs<br />
: set for any IPv6 virtual service<br />
;$ipvsid_000<br />
: set to ID of virtual service<br />
;$unused<br />
: set for such virtual services which do not have any RS Pool-Load Balancer links<br />
<br />
=== Real server pool tags ===<br />
;$any_rsp<br />
: set for all RS pools (which is the same as $any_ipv4rsp)<br />
;$any_ipv4rsp<br />
: set for all RS pools (RS pools can contain both IPv4 and IPv6 addresses)<br />
;$ipv4rspid_000<br />
: set to RS pool ID<br />
;$unused<br />
: set for such RS poold which do not have any Virtual Service-Load Balancer links<br />
<br />
=== Operation-specific tags ===<br />
;$fromvlan_NNNN<br />
: Set, when a port is being removed from VLAN with the given VLAN ID (by means of LiveVLANs or 802.1Q ports feature).<br />
;$tovlan_NNNN<br />
: Likewise, when a port is being added to a VLAN.<br />
;$vlan_NNNN<br />
: Likewise, when a port is being either added OR removed, equivalent to "{$fromvlan_NNNN} or {$tovlan_NNNN}" RackCode expression.</div>Adoom42https://wiki.racktables.org/index.php?title=FAQ&diff=697FAQ2014-07-16T14:34:28Z<p>Adoom42: /* Is there a simpler way to export IP addresses? */</p>
<hr />
<div>= RackTables FAQ =<br />
<br />
== How do I edit this wiki? ==<br />
Send a message to devteam@racktables.org.<br />
<br />
== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==<br />
RackTables only supports some specific switch models, and yours is not one of them. <br />
<br />
There are two ways to add support for new switch models. Both involve [http://bugs.racktables.org/bug_report_page.php filing a Mantis ticket].<br />
=== Write a patch yourself. ===<br />
* Review [[RackTablesDevelGuide#SNMP_sync|SNMP sync]] for background information.<br />
* Attach the patch to the Mantis ticket.<br />
=== Ask the developers to write a patch for you. ===<br />
The following information is necessary.<br />
* The exact model/part number of the device.<br />
* For a device which features SFP (GBIC, X2 etc) pluggable ports, specify which of these pluggable ports are "combo" (IOW, alternate socket for a copper port under the same name) and which are standalone ports.<br />
If possible, add the following information:<br />
* Manufacturer's markup of device's ports (this can be "21, 22, 23, 24", "21X, 22X, 23X, 24X" or even "21, 22, 23C, 23F, 24C, 24F")<br />
* Dump of SNMP info:<br />
<pre><br />
snmpwalk -v 1 -c public switchname sysDescr.0<br />
snmpwalk -On -v 1 -c public switchname sysObjectID.0<br />
snmpwalk -v 1 -c public switchname ifTable<br />
</pre><br />
If the device is modular or stackable, also walk ENTITY-MIB:<br />
<pre><br />
snmpwalk -v 1 -c public switchname .1.3.6.1.2.1.47<br />
</pre><br />
<br />
Attach the information to the Mantis ticket. Do not post it inline, as it consumes too much screen real estate.<br />
<br />
== Rack thumb images are broken ==<br />
There are two common reasons for this:<br />
# A mis-formatted local.php extension file. For images to work correctly, every PHP file of your RackTables, which begins with '''<?php''' tag, CAN NOT have a newline before the tag. Every PHP file of your RackTables, which ends with '''?>''' tag, CAN NOT have a newline after the tag.<br />
# GD library is not working (although it probably was at the time of installation). This can be confirmed by means of phpinfo() and fixed with the help of package manager of your server and RackTables README file.<br />
<br />
== How do I browse objects by object type? ==<br />
FILL ME IN<br />
<br />
== How do I handle blade systems/modular switches? ==<br />
You can have one object represent the chassis, and other objects represent the blades. See the documentation on [[RackTablesUserGuide#Containers|Containers]] for details.<br />
<br />
== How do I re-order racks in a row? ==<br />
In versions prior to 0.20, RackTables sorts in alphabetical order. A work-around is to prefix each rack's name with a number:<br />
* "01 F14"<br />
* "02 E14"<br />
* "03 D14"<br />
* "04 C14"<br />
* "05 B14"<br />
* "06 A14"<br />
<br />
Starting with 0.20, you can manually sort racks. View the row, then click the "Manage racks" tab.<br />
<br />
== How do I log out (and log in after that?) ==<br />
To log out: Use the "Click here to logout" link. When presented with the username/password prompt, do not enter anything. Instead, press "Cancel".<br />
<br />
To log in: Press your browser's "back" button to return to any of the normal pages (without "index.php?logout" in the URL) and enter your username/password.<br />
<br />
== How do I enable IPv4 for object type X in versions before 0.20.6? ==<br />
Answered by Ray Robertson:<br />
<code><br />
Configuration --> User Interface --> Change<br />
<br />
Edit the entry for 'List source: IPv4-enabled objects'<br />
<br />
e.g.<br />
List source: IPv4-enabled objects {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798}<br />
<br />
To determine an object's typeid, hover your mouse pointer over the 'Object type' field when viewing the object. The typeid will be revealed in the URL.<br />
</code><br />
<br />
<br />
'''Scenario:''' <br />
<br />
At Company X you have a proprietary transceiver-type device that is network accessible & can be assigned an IP. You add a new RackObjectType called "Transceiver". To add the IPv4 tab to new "Transceiver" objects, do the following.<br />
<br />
<code><br />
1. Navigate to Main > Configuration > Dictionary > RackObjectType.<br />
<br />
2. Mouse-over the new RackObjectType you created, in this case "Transceiver". In this example, the Transceiver typeid is 50012.<br />
<br />
3. Now navigate to Main > Configuration > User Interface > Change.<br />
<br />
4. Scroll down to the item/entry "List source: IPv4-enabled objects". <br />
<br />
5. Now go to the end of the line, and enter "or {$typeid_50012}". <br />
<br />
6. Your new line looks like: {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798} or {$typeid_50012}<br />
<br />
7. Save changes.<br />
<br />
8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.<br />
</code><br />
<br />
==How do I decode the IPv4 addresses stored in RackTables MySQL database?==<br />
RackTables stores all IPv4 addresses in their natural representation (32-bit unsigned integers like 180879936). The most reliable way is to use RackTables PHP function spotEntity(), which will return a structure filled with assorted fields, including a dotted-quad representation of IP address. If for whatever reason you decide to fetch the data directly from MySQL database, the simplest way of converting the intergers to dotted-quad (10.200.2.64) form and back is to use MySQL's functions INET_NTOA() and INET_ATON() respectively:<br />
<pre><br />
mysql> SELECT ip, INET_NTOA(ip), mask FROM IPv4Network;<br />
+-----------+---------------+------+<br />
| ip | INET_NTOA(ip) | mask |<br />
+-----------+---------------+------+<br />
| 180879360 | 10.200.0.0 | 31 |<br />
| 180879362 | 10.200.0.2 | 31 |<br />
| 180879364 | 10.200.0.4 | 31 |<br />
| 180879366 | 10.200.0.6 | 31 |<br />
| 180879616 | 10.200.1.0 | 26 |<br />
| 180879680 | 10.200.1.64 | 26 |<br />
| 180879872 | 10.200.2.0 | 26 |<br />
| 180879936 | 10.200.2.64 | 26 |<br />
| 180880192 | 10.200.3.64 | 26 |<br />
| 180880384 | 10.200.4.0 | 26 |<br />
| 180880448 | 10.200.4.64 | 26 |<br />
+-----------+---------------+------+<br />
11 rows in set (0.00 sec)<br />
</pre><br />
<br />
==Is there a simpler way to export IP addresses?==<br />
The method above has some disadvantages: IPv6 addresses are stored in different format, you aren't able to filter the objects to export using RackCode. In general, users should prefer to write PHP exporters rather than SQL ones. Here is an example of a simple exporter printing all IP allocaions for objects tagged by {debian wheezy}:<br />
<br />
<pre><br />
<?php<br />
$script_mode = TRUE;<br />
require 'wwwroot/inc/init.php';<br />
foreach (scanRealmByText ('object', '{debian wheezy}') as $object)<br />
{<br />
amplifyCell ($object);<br />
foreach ($object['ipv4'] + $object['ipv6'] as $ip_bin => $alloc)<br />
echo implode ("\t", [ $object['name'], $alloc['osif'], ip_format ($ip_bin) ]) . "\n";<br />
}<br />
</pre><br />
<br />
==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==<br />
This is a known issue. The workaround is to upgrade from 0.17.x to 0.18.7, then to 0.19.x. Release 0.18.7 can be downloaded directly from the git repository: https://github.com/RackTables/racktables/zipball/RackTables-0.18.7<br />
<br />
==How do I manage tags on a series of objects (networks etc) automaticaly?==<br />
<pre><br />
<?php<br />
<br />
$script_mode = TRUE;<br />
include '/usr/local/racktables/wwwroot/inc/init.php';<br />
<br />
# add tag "right" to each object tagged "left"<br />
$added = getTagByName ('right');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
rebuildTagChainForEntity ('object', $object['id'], array ($added));<br />
<br />
# remove tag "left" from each object tagged "right"<br />
$removed = getTagByName ('left');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
deleteTagForEntity ('object', $object['id'], $removed['id']);<br />
<br />
?><br />
</pre><br />
<br />
= RackTables contributions =<br />
== How can I visualise network topology? ==<br />
See [[Visualisation with GraphViz]] for ideas using GraphViz.</div>Adoom42https://wiki.racktables.org/index.php?title=FAQ&diff=695FAQ2014-06-24T15:37:53Z<p>Adoom42: use numeric option when querying sysObjectID</p>
<hr />
<div>= RackTables FAQ =<br />
<br />
== How do I edit this wiki? ==<br />
Send a message to devteam@racktables.org.<br />
<br />
== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==<br />
RackTables only supports some specific switch models, and yours is not one of them. <br />
<br />
There are two ways to add support for new switch models. Both involve [http://bugs.racktables.org/bug_report_page.php filing a Mantis ticket].<br />
=== Write a patch yourself. ===<br />
* Review [[RackTablesDevelGuide#SNMP_sync|SNMP sync]] for background information.<br />
* Attach the patch to the Mantis ticket.<br />
=== Ask the developers to write a patch for you. ===<br />
The following information is necessary.<br />
* The exact model/part number of the device.<br />
* For a device which features SFP (GBIC, X2 etc) pluggable ports, specify which of these pluggable ports are "combo" (IOW, alternate socket for a copper port under the same name) and which are standalone ports.<br />
If possible, add the following information:<br />
* Manufacturer's markup of device's ports (this can be "21, 22, 23, 24", "21X, 22X, 23X, 24X" or even "21, 22, 23C, 23F, 24C, 24F")<br />
* Dump of SNMP info:<br />
<pre><br />
snmpwalk -v 1 -c public switchname sysDescr.0<br />
snmpwalk -On -v 1 -c public switchname sysObjectID.0<br />
snmpwalk -v 1 -c public switchname ifTable<br />
</pre><br />
If the device is modular or stackable, also walk ENTITY-MIB:<br />
<pre><br />
snmpwalk -v 1 -c public switchname .1.3.6.1.2.1.47<br />
</pre><br />
<br />
Attach the information to the Mantis ticket. Do not post it inline, as it consumes too much screen real estate.<br />
<br />
== Rack thumb images are broken ==<br />
There are two common reasons for this:<br />
# A mis-formatted local.php extension file. For images to work correctly, every PHP file of your RackTables, which begins with '''<?php''' tag, CAN NOT have a newline before the tag. Every PHP file of your RackTables, which ends with '''?>''' tag, CAN NOT have a newline after the tag.<br />
# GD library is not working (although it probably was at the time of installation). This can be confirmed by means of phpinfo() and fixed with the help of package manager of your server and RackTables README file.<br />
<br />
== How do I browse objects by object type? ==<br />
FILL ME IN<br />
<br />
== How do I handle blade systems/modular switches? ==<br />
You can have one object represent the chassis, and other objects represent the blades. See the documentation on [[RackTablesUserGuide#Containers|Containers]] for details.<br />
<br />
== How do I re-order racks in a row? ==<br />
In versions prior to 0.20, RackTables sorts in alphabetical order. A work-around is to prefix each rack's name with a number:<br />
* "01 F14"<br />
* "02 E14"<br />
* "03 D14"<br />
* "04 C14"<br />
* "05 B14"<br />
* "06 A14"<br />
<br />
Starting with 0.20, you can manually sort racks. View the row, then click the "Manage racks" tab.<br />
<br />
== How do I log out (and log in after that?) ==<br />
To log out: Use the "Click here to logout" link. When presented with the username/password prompt, do not enter anything. Instead, press "Cancel".<br />
<br />
To log in: Press your browser's "back" button to return to any of the normal pages (without "index.php?logout" in the URL) and enter your username/password.<br />
<br />
== How do I enable IPv4 for object type X in versions before 0.20.6? ==<br />
Answered by Ray Robertson:<br />
<code><br />
Configuration --> User Interface --> Change<br />
<br />
Edit the entry for 'List source: IPv4-enabled objects'<br />
<br />
e.g.<br />
List source: IPv4-enabled objects {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798}<br />
<br />
To determine an object's typeid, hover your mouse pointer over the 'Object type' field when viewing the object. The typeid will be revealed in the URL.<br />
</code><br />
<br />
<br />
'''Scenario:''' <br />
<br />
At Company X you have a proprietary transceiver-type device that is network accessible & can be assigned an IP. You add a new RackObjectType called "Transceiver". To add the IPv4 tab to new "Transceiver" objects, do the following.<br />
<br />
<code><br />
1. Navigate to Main > Configuration > Dictionary > RackObjectType.<br />
<br />
2. Mouse-over the new RackObjectType you created, in this case "Transceiver". In this example, the Transceiver typeid is 50012.<br />
<br />
3. Now navigate to Main > Configuration > User Interface > Change.<br />
<br />
4. Scroll down to the item/entry "List source: IPv4-enabled objects". <br />
<br />
5. Now go to the end of the line, and enter "or {$typeid_50012}". <br />
<br />
6. Your new line looks like: {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798} or {$typeid_50012}<br />
<br />
7. Save changes.<br />
<br />
8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.<br />
</code><br />
<br />
==How do I decode the IPv4 addresses stored in RackTables MySQL database?==<br />
RackTables stores all IPv4 addresses in their natural representation (32-bit unsigned integers like 180879936). The most reliable way is to use RackTables PHP function spotEntity(), which will return a structure filled with assorted fields, including a dotted-quad representation of IP address. If for whatever reason you decide to fetch the data directly from MySQL database, the simplest way of converting the intergers to dotted-quad (10.200.2.64) form and back is to use MySQL's functions INET_NTOA() and INET_ATON() respectively:<br />
<pre><br />
mysql> SELECT ip, INET_NTOA(ip), mask FROM IPv4Network;<br />
+-----------+---------------+------+<br />
| ip | INET_NTOA(ip) | mask |<br />
+-----------+---------------+------+<br />
| 180879360 | 10.200.0.0 | 31 |<br />
| 180879362 | 10.200.0.2 | 31 |<br />
| 180879364 | 10.200.0.4 | 31 |<br />
| 180879366 | 10.200.0.6 | 31 |<br />
| 180879616 | 10.200.1.0 | 26 |<br />
| 180879680 | 10.200.1.64 | 26 |<br />
| 180879872 | 10.200.2.0 | 26 |<br />
| 180879936 | 10.200.2.64 | 26 |<br />
| 180880192 | 10.200.3.64 | 26 |<br />
| 180880384 | 10.200.4.0 | 26 |<br />
| 180880448 | 10.200.4.64 | 26 |<br />
+-----------+---------------+------+<br />
11 rows in set (0.00 sec)<br />
</pre><br />
<br />
==Is there a simpler way to export IP addresses?==<br />
The method above has some disadvantages: IPv6 addresses are stored in different format, you don't able to filter the objects to export using RackCode. In general, users should prefer to write PHP exporters rather than SQL ones. Here is an example of a simple exporter printing all IP allocaions for objects tagged by {debian wheezy}:<br />
<br />
<pre><br />
<?php<br />
$script_mode = TRUE;<br />
require 'wwwroot/inc/init.php';<br />
foreach (scanRealmByText ('object', '{debian wheezy}') as $object)<br />
{<br />
amplifyCell ($object);<br />
foreach ($object['ipv4'] + $object['ipv6'] as $ip_bin => $alloc)<br />
echo implode ("\t", [ $object['name'], $alloc['osif'], ip_format ($ip_bin) ]) . "\n";<br />
}<br />
</pre><br />
<br />
==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==<br />
This is a known issue. The workaround is to upgrade from 0.17.x to 0.18.7, then to 0.19.x. Release 0.18.7 can be downloaded directly from the git repository: https://github.com/RackTables/racktables/zipball/RackTables-0.18.7<br />
<br />
==How do I manage tags on a series of objects (networks etc) automaticaly?==<br />
<pre><br />
<?php<br />
<br />
$script_mode = TRUE;<br />
include '/usr/local/racktables/wwwroot/inc/init.php';<br />
<br />
# add tag "right" to each object tagged "left"<br />
$added = getTagByName ('right');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
rebuildTagChainForEntity ('object', $object['id'], array ($added));<br />
<br />
# remove tag "left" from each object tagged "right"<br />
$removed = getTagByName ('left');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
deleteTagForEntity ('object', $object['id'], $removed['id']);<br />
<br />
?><br />
</pre><br />
<br />
= RackTables contributions =<br />
== How can I visualise network topology? ==<br />
See [[Visualisation with GraphViz]] for ideas using GraphViz.</div>Adoom42https://wiki.racktables.org/index.php?title=Main_Page&diff=689Main Page2014-04-14T21:59:55Z<p>Adoom42: removed reference to unsigned cert (replaced with a signed one)</p>
<hr />
<div>[[File:RackTables-development-roadmap-2013Q4.png|356px|thumb|right]]<br />
* for RackTables users<br />
** [[RackTablesInstallHowto | Installation HOWTO]]<br />
** [[RackTablesAdminGuide | Administrator's guide]]<br />
** [[RackTablesUserGuide | User's guide]]<br />
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)<br />
** [[FAQ]]<br />
** [[LDAP | LDAP authentication]]<br />
** [[SAML | SAML authentication]]<br />
* for RackTables hackers<br />
** [[SourceCode | Working with RackTables source code]]<br />
** [[RackTablesDevelGuide | Developer's guide]]<br />
** [[FeatureWishlist | Feature wishlist]]<br />
** [[Gateways | Extending RackTables with gateways]]<br />
* for development team<br />
** [[NewRelease | Checklist and procedures to make a new release]]<br />
** [[ProjectInfrastructure | Project infrastructure]]<br />
** [[Roadmap]]<br />
<br />
<br />
To use this site over an SSL connection, visit [https://wiki.racktables.org/ https://wiki.racktables.org/]</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=659PortLinking2013-12-12T20:41:17Z<p>Adoom42: /* Multi-port cable */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all links associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same (a port may have both physical and logical links, both ending at the same port).<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one origin and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should perform a trace of every port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router-Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection. If you assume the adapter is part of the object, it can be classified as NEMA 5/15P.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=657PortLinking2013-12-12T20:33:42Z<p>Adoom42: /* WAN Links */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all links associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same (a port may have both physical and logical links, both ending at the same port).<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one origin and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should perform a trace of every port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router-Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=655PortLinking2013-12-12T20:32:34Z<p>Adoom42: /* Patch Panels */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all links associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same (a port may have both physical and logical links, both ending at the same port).<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one origin and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should perform a trace of every port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=653PortLinking2013-12-12T20:27:42Z<p>Adoom42: /* Circuits */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all links associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same (a port may have both physical and logical links, both ending at the same port).<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one origin and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should trace each port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=651PortLinking2013-12-12T20:26:58Z<p>Adoom42: /* Tracing Feature */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all links associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same (a port may have both physical and logical links, both ending at the same port).<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one start and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should trace each port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=649PortLinking2013-12-12T20:22:22Z<p>Adoom42: /* Schema */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all links associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same.<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one start and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should trace each port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=647PortLinking2013-12-12T20:20:44Z<p>Adoom42: /* Core Goals */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all links associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns which apply to both data and power links:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same.<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one start and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should trace each port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=641PortLinking2013-12-09T21:21:52Z<p>Adoom42: /* Core Goals */</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching its final destination.<br />
* Graph the traversal of all link(s) associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns which apply to both data and power links:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same.<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one start and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should trace each port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=Roadmap&diff=639Roadmap2013-12-09T21:16:00Z<p>Adoom42: </p>
<hr />
<div>= 0.21 =<br />
* Discover and re-discover modular & stackable devices<br />
* Cable tracing<br />
* Duplicate IPv4 networks<br />
* Merge the IPv4 & IPv6 tables and codebase<br />
* Purge old-style VS configuration<br />
* Properly escape all strings containing content from the database<br />
* Replace HTTP authentication with a login page<br />
* Refactor caching<br />
* HTML5 UI overhaul<br />
* Separate rendering functions by portlets, introduce portlet schema in navigation.php<br />
* REST API</div>Adoom42https://wiki.racktables.org/index.php?title=File:Key.jpg&diff=579File:Key.jpg2013-12-01T19:56:57Z<p>Adoom42: </p>
<hr />
<div></div>Adoom42https://wiki.racktables.org/index.php?title=File:Patch_panels.jpg&diff=577File:Patch panels.jpg2013-12-01T19:56:48Z<p>Adoom42: </p>
<hr />
<div></div>Adoom42https://wiki.racktables.org/index.php?title=File:Wan_connections.jpg&diff=575File:Wan connections.jpg2013-12-01T19:56:41Z<p>Adoom42: </p>
<hr />
<div></div>Adoom42https://wiki.racktables.org/index.php?title=File:Modems.jpg&diff=573File:Modems.jpg2013-12-01T19:56:29Z<p>Adoom42: </p>
<hr />
<div></div>Adoom42https://wiki.racktables.org/index.php?title=File:Splicing.jpg&diff=571File:Splicing.jpg2013-12-01T19:56:22Z<p>Adoom42: </p>
<hr />
<div></div>Adoom42https://wiki.racktables.org/index.php?title=File:Bonding.jpg&diff=569File:Bonding.jpg2013-12-01T19:56:10Z<p>Adoom42: </p>
<hr />
<div></div>Adoom42https://wiki.racktables.org/index.php?title=File:Vm_links.jpg&diff=567File:Vm links.jpg2013-12-01T19:55:42Z<p>Adoom42: </p>
<hr />
<div></div>Adoom42https://wiki.racktables.org/index.php?title=PortLinking&diff=565PortLinking2013-12-01T19:55:20Z<p>Adoom42: Created page with "= Core Goals = * Determine which port(s) a specified port is physically connected to. * Determine which port(s) a specified port is logically connected to. * Graph the link(s)..."</p>
<hr />
<div>= Core Goals =<br />
* Determine which port(s) a specified port is physically connected to.<br />
* Determine which port(s) a specified port is logically connected to.<br />
* Graph the link(s) a port traverses before reaching the final destination.<br />
* Graph the traversal of all link(s) associated to an object.<br />
* Provide the ability to trace ports of "contained" objects.<br />
<br />
= DB Changes =<br />
== Schema ==<br />
Current columns in the Link table:<br />
* porta<br />
* portb<br />
* cable (cable ID)<br />
<br />
New columns which apply to both data and power links:<br />
* type (physical, logical or unspecified)<br />
* cable type (reference a dictionary entry)<br />
* cable color (varchar [loose] or reference a dictionary entry [strict]?)<br />
* length<br />
* notes<br />
<br />
Current columns of the Port table:<br />
* id<br />
* object_id<br />
* name<br />
* iif_id<br />
* type<br />
* l2address (only applies to data ports)<br />
* reservation_comment<br />
* label<br />
<br />
New columns which only apply to power ports in most cases (PoE ports are the exception):<br />
* voltage<br />
* maximum wattage<br />
* average wattage<br />
<br />
== New Port Types ==<br />
It would be helpful to provide an image of each type. Also, the types listed are used in the USA, international support should be added.<br />
=== Power (receptacle) ===<br />
* IEC C14<br />
* IEC C20<br />
* NEMA 5-15R<br />
* NEMA 5-20R<br />
* NEMA L5-20R<br />
* NEMA L6-20R<br />
* NEMA L6-30R<br />
<br />
=== Power (plug) ===<br />
* IEC C13<br />
* IEC C19<br />
* NEMA 5-15P<br />
* NEMA L5-20P<br />
* NEMA L5-30P<br />
* NEMA L6-20P<br />
* NEMA L6-30P<br />
* NEMA L15-20P (208V Delta)<br />
* NEMA L15-30P (208V Delta)<br />
* NEMA L21-20P (208V WYE)<br />
* NEMA L21-30P (208V WYE)<br />
* NEMA CS8365C (208V Delta)<br />
<br />
=== Cable Types ===<br />
* Thicknet Coaxial (10Mb)<br />
* Cat-3<br />
* Cat-4<br />
* Cat-5<br />
* Cat-5e<br />
* Cat-6<br />
* Cat-7<br />
* Multi-mode Fiber<br />
* Single-mode Fiber<br />
* Twin-axial (10Gb)<br />
<br />
= Tracing Feature =<br />
When tracing a port or an object, the user should be able to choose which links are included in the graph:<br />
* Port Type<br />
** Data<br />
** Power<br />
** Both<br />
* Link Type<br />
** Physical<br />
** Logical<br />
** Both<br />
<br />
The appearance of links on the graph should vary depending on the type. If the color of a link is specified, it should be used on the graph.<br />
<br />
The user should be able to specify the recursion depth. A default could be stored in the Config table, but the user should be able to modify the depth setting by changing a field in the trace pop-up window. If an object or port has additional links which are not displayed due to the depth limit, it should be marked somehow (perhaps colored green). Clicking on it would reload the page with that object/port becoming the "subject" which is traced.<br />
<br />
The recursive trace function needs to be modified to handle all link types. Loops could become very common if both types were treated the same.<br />
<br />
= Circuits =<br />
The tracing feature described above depends on intermediate ports being linked more than once. Due to the one-to-many design, a traversed link may have multiple endpoints.<br />
<br />
An alternative is to use manually-defined circuits, which would have only one start and one endpoint. In the case of links with multiple endpoints, multiple circuits would need to be defined.<br />
<br />
Circuit table definition:<br />
* id<br />
* name (some may want to name circuits by hand)<br />
* description<br />
* start_port_id (calculated, not directly user-modifiable)<br />
* end_port_id (calculated, not directly user-modifiable)<br />
<br />
CircuitStep table definition:<br />
* id<br />
* circuit_id<br />
* step<br />
* start_port_id<br />
* end_port_id<br />
<br />
== Example: Through Patch Panels ==<br />
A server is connected to a switch, passing through two patch panels. Assume that 8P8C ports use '1-88' as their type.<br />
<br />
<pre><br />
SELECT * FROM Port;<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| id | object_id | name | iif_id | type | l2address | reservation_comment | label |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
| 1 | 1 | eth0 | 1 | 24 | NULL | NULL | |<br />
| 2 | 2 | 8 | 1 | 88 | NULL | NULL | |<br />
| 3 | 3 | 8 | 1 | 88 | NULL | NULL | |<br />
| 4 | 4 | gi0 | 1 | 24 | NULL | NULL | |<br />
+----+-----------+------+--------+------+-----------+---------------------+-------+<br />
<br />
SELECT * FROM Circuit WHERE id = 1;<br />
+----+------+-------------+---------------+-------------+<br />
| id | name | description | start_port_id | end_port_id |<br />
+----+------+-------------+---------------+-------------+<br />
| 1 | C219 | host1 to R1 | 1 | 4 |<br />
+----+------+-------------+---------------+-------------+<br />
<br />
SELECT * FROM CircuitStep WHERE circuit_id = 1;<br />
+----+------------+------+---------------+-------------+<br />
| id | circuit_id | step | start_port_id | end_port_id |<br />
+----+------------+------+---------------+-------------+<br />
| 1 | 1 | 1 | 1 | 2 |<br />
| 2 | 1 | 2 | 2 | 3 |<br />
| 3 | 1 | 3 | 3 | 4 |<br />
+----+------------+------+---------------+-------------+<br />
</pre><br />
<br />
== Notes ==<br />
* Using the circuit model, the existing Link table would only be used to document physical links. All logical links would need to be replaced with circuits.<br />
* A significant amount of preemptive logic would need to be written to make circuit management feasible. Consider these cases:<br />
** When racking an object, ports must be linked and circuits must be created. This imposes more labor than auto-discovering paths using the original recursive traceroute logic.<br />
*** Original: Link eth0 to PP1 port 1 (record the physical connection).<br />
*** Circuit-based: Link eth0 to port 1 (record the physical connection). Create a new circuit, noting connections to PP1 port 1, PP2 port 1 and R1 port gi0.<br />
** What happens when an intermediate port or object is deleted?<br />
* In the provided table definition, Start and End port IDs are included in the Circuit table to reduce the effort required to determine the values. This is a form of de-normalization. Also, the values may become inaccurate if CircuitStep data is manually altered. Circuits use one-to-one links, so a recursive PHP or MySQL function could be used instead. A MySQL function may not be feasible because recursive calls are disabled by default. A PHP function may be too resource intensive, notably when viewing an object with several hundred ports. Further testing is warranted.<br />
<br />
= Misc Notes =<br />
* In the case of breaker panels, one-to-many links are common. A 120v circuit uses one breaker, a 208v circuit uses two, and a three-phase circuit uses three.<br />
* The CDP/LLDP/802.1Q features, as they exist today, expect a direct link between neighbor ports to exist. It may be either physical or logical (or both?).<br />
* For simple cases, such as connecting a server directly to a switch, defining two links could be considered too much work. Users shouldn’t be forced to define both physical and logical links between ports.<br />
<br />
= Use Cases =<br />
Key:<br />
[[Image:key.jpg]]<br />
<br />
== Patch Panels ==<br />
[[Image:patch_panels.jpg]]<br />
<br />
* From a logical perspective, Rack Switch-Fa0/1 is directly connected to Core Switch1-Gi0/7.<br />
* Tracing a port should only display items which directly participate in the path.<br />
* Tracing an object should trace each port and merge the results.<br />
* Tracing can be done using recursion of physical links, since intermediate ports are linked twice, while end-point ports are only linked once.<br />
<br />
== WAN Links ==<br />
[[Image:wan_connections.jpg]]<br />
<br />
* From a logical perspective, Site A Router-Fa0/1 is directly connected to Site B Router Ser0.<br />
* The ISP device is past the point of demarcation, totally outside the control of the customer. The customer may or may not wish to document ISP connections at the same level of detail as connections under his control.<br />
* Adding a port compatibility rule to allow 100Base-Tx connections to Fiber SC ports could be considered a sub-optimal approach.<br />
* Tracing cannot be done using recursion of physical links, since intermediate ports are only linked once.<br />
* Establishing additional “internal” links between the "LAN" and "WAN" ports of devices would allow tracing to succeed.<br />
<br />
== Physical Multi-point Links ==<br />
=== Multi-port cable ===<br />
[[Image:modems.jpg]]<br />
<br />
* Each modem uses an AC adapter with a proprietary connection.<br />
* The same design can be applied to "Y" power cables which connect directly from the input source to device power supplies.<br />
* An octo-cable is used to power up to eight modems from a single outlet.<br />
* A similar methodology applies to QSFP+ connections – a one-to-four "breakout" cable.<br />
<br />
=== Splicing ===<br />
[[Image:splicing.jpg]]<br />
<br />
* The 66 block is considered "horizontal wiring".<br />
* The bundle of cables between the 66 block and the ISP is considered "vertical cabling".<br />
<br />
== Bonding ==<br />
[[Image:bonding.jpg]]<br />
<br />
* Server is a Linux host. eth0 and eth1 are slaves of the bond0 virtual interface, which uses mode 4 (802.3ad).<br />
* Switch is a Cisco switch with an LACP PortChannel interface containing Gi0/1 and Gi0/2 as members.<br />
* The example equally applies to switch-to-switch interconnections.<br />
<br />
== Virtual Links ==<br />
[[Image:vm_links.jpg]]<br />
<br />
* A virtual switch may contain both physical (uplink) and virtual (connect to VMs) ports. It may be used on a single host or distributed across multiple hosts.</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=563FeatureWishlist2013-12-01T05:10:50Z<p>Adoom42: </p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys<br />
*** EntityLink table<br />
**** Verify that referenced rows exist<br />
**** Validate parent/child relationships (parent_id != child_id, a child cannot be its own grandparent)<br />
*** Config settings such as IPV4OBJ_LISTSRC (an object type may be removed from the list, even if objects of that type exist and have IP addresses assigned)<br />
* Manage plugins from the web interface<br />
** Install/uninstall, enable/disable capability capability<br />
** Install/uninstall features handle DB table creation/destruction<br />
* Move object Make/Model information out of the Dictionary<br />
** Additional information needs to be stored. Using dedicated fields is a cleaner approach than the current one (stapling it on, separated by GPASS or other % wrappers)<br />
** Suggested fields:<br />
*** Make<br />
*** Model<br />
*** Category (replace chapter_id, sample types are server, network switch, etc.)<br />
*** Type (rack-mountable object, module, component)<br />
*** Height, depth (only applies to rack-mountable objects)<br />
*** Rows, Columns, Orientation (only applies to chassis objects)<br />
*** Template (described below)<br />
* Object templates<br />
** The current SNMP discovery functionality covers two core areas - interfaces and attributes. If an object is modular, the number and type of interfaces may vary. Some objects are static, such as non-stackable switches. Using a template for static devices would ease the process of adding them, especially in cases where there is no SNMP support in RackTables.<br />
** There are also cases where SNMP-derived information isn't necessary. A user may want to add the object in order to document the rackspace allocation and port connections. Documenting port MAC addresses and other attributes such as serial numbers and SW version provides limited or no value. Using a pre-defined template, ports could be added during the object creation process. If desired, SNMP re-discovery could add the missing information at a later date.<br />
* Refactor user management<br />
** The first time a user logs in via an external authentication source (LDAP), a record should be auto-added to the UserAccount table.<br />
** Today, user accounts cannot be deleted. Users should never be deleted from the DB because various tables record their actions. Add a 'deleted' column to the UserAccount table and provide a way to 'delete' them from the web interface (the 'deleted' column would be set to true').<br />
** The user_name column must be unique, but only for 'undeleted' accounts. Use DB triggers (ideal) or PHP code to ensure uniqueness.<br />
** Change existing tables to reference UserAccount by user_id instead of user_name (IPv(4|6)Log, MountOperation, ObjectHistory, ObjectLog, PortLog, TagStorage, UserConfig, VLANSwitchTemplate).</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=561FeatureWishlist2013-11-28T22:10:42Z<p>Adoom42: </p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys<br />
*** EntityLink table<br />
*** Config settings such as IPV4OBJ_LISTSRC (an object type may be removed from the list, even if objects of that type exist and have IP addresses assigned)<br />
* Manage plugins from the web interface<br />
** Install/uninstall, enable/disable capability capability<br />
** Install/uninstall features handle DB table creation/destruction<br />
* Move object Make/Model information out of the Dictionary<br />
** Additional information needs to be stored. Using dedicated fields is a cleaner approach than the current one (stapling it on, separated by GPASS or other % wrappers)<br />
** Suggested fields:<br />
*** Make<br />
*** Model<br />
*** Category (replace chapter_id, sample types are server, network switch, etc.)<br />
*** Type (rack-mountable object, module, component)<br />
*** Height, depth (only applies to rack-mountable objects)<br />
*** Rows, Columns, Orientation (only applies to chassis objects)<br />
*** Template (described below)<br />
* Object templates<br />
** The current SNMP discovery functionality covers two core areas - interfaces and attributes. If an object is modular, the number and type of interfaces may vary. Some objects are static, such as non-stackable switches. Using a template for static devices would ease the process of adding them, especially in cases where there is no SNMP support in RackTables.<br />
** There are also cases where SNMP-derived information isn't necessary. A user may want to add the object in order to document the rackspace allocation and port connections. Documenting port MAC addresses and other attributes such as serial numbers and SW version provides limited or no value. Using a pre-defined template, ports could be added during the object creation process. If desired, SNMP re-discovery could add the missing information at a later date.<br />
* Refactor user management<br />
** Today, user accounts cannot be deleted. Users should never be deleted from the DB because various tables record their actions. Add a 'deleted' column to the UserAccounts table and provide a way to 'delete' them from the web interface (the 'deleted' column would be set to true').<br />
** The user_name column must be unique, but only for 'undeleted' accounts. Use DB triggers (ideal) or PHP code to ensure uniqueness.<br />
** Change existing tables to reference UserAccount by user_id instead of user_name (IPv(4|6)Log, MountOperation, ObjectHistory, ObjectLog, PortLog, TagStorage, UserConfig, VLANSwitchTemplate).</div>Adoom42https://wiki.racktables.org/index.php?title=Roadmap&diff=559Roadmap2013-11-28T18:04:22Z<p>Adoom42: /* 0.21 */</p>
<hr />
<div>= 0.21 =<br />
* Discover and re-discover modular & stackable devices<br />
* Cable tracing<br />
* Duplicate IPv4 networks<br />
* Merge the IPv4 & IPv6 tables and codebase<br />
* Purge old-style VS configuration<br />
* Properly escape all strings containing content from the database<br />
* Replace HTTP authentication with a login page<br />
* Refactor caching<br />
* HTML5 UI overhaul</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=557FeatureWishlist2013-11-25T19:56:59Z<p>Adoom42: </p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys<br />
*** EntityLink table<br />
*** Config settings such as IPV4OBJ_LISTSRC (an object type may be removed from the list, even if objects of that type exist and have IP addresses assigned)<br />
* Manage plugins from the web interface<br />
** Install/uninstall, enable/disable capability capability<br />
** Install/uninstall features handle DB table creation/destruction<br />
* Move object Make/Model information out of the Dictionary<br />
** Additional information needs to be stored. Using dedicated fields is a cleaner approach than the current one (stapling it on, separated by GPASS or other % wrappers)<br />
** Suggested fields:<br />
*** Make<br />
*** Model<br />
*** Category (replace chapter_id, sample types are server, network switch, etc.)<br />
*** Type (rack-mountable object, module, component)<br />
*** Height, depth (only applies to rack-mountable objects)<br />
*** Rows, Columns, Orientation (only applies to chassis objects)<br />
*** Template (described below)<br />
* Object templates<br />
** The current SNMP discovery functionality covers two core areas - interfaces and attributes. If an object is modular, the number and type of interfaces may vary. Some objects are static, such as non-stackable switches. Using a template for static devices would ease the process of adding them, especially in cases where there is no SNMP support in RackTables.<br />
** There are also cases where SNMP-derived information isn't necessary. A user may want to add the object in order to document the rackspace allocation and port connections. Documenting port MAC addresses and other attributes such as serial numbers and SW version provides limited or no value. Using a pre-defined template, ports could be added during the object creation process. If desired, SNMP re-discovery could add the missing information at a later date.</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=555FeatureWishlist2013-11-25T19:51:18Z<p>Adoom42: </p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys (EntityLink, for example)<br />
* Manage plugins from the web interface<br />
** Install/uninstall, enable/disable capability capability<br />
** Install/uninstall features handle DB table creation/destruction<br />
* Move object Make/Model information out of the Dictionary<br />
** Additional information needs to be stored. Using dedicated fields is a cleaner approach than the current one (stapling it on, separated by GPASS or other % wrappers)<br />
** Suggested fields:<br />
*** Make<br />
*** Model<br />
*** Category (replace chapter_id, sample types are server, network switch, etc.)<br />
*** Type (rack-mountable object, module, component)<br />
*** Height, depth (only applies to rack-mountable objects)<br />
*** Rows, Columns, Orientation (only applies to chassis objects)<br />
*** Template (described below)<br />
* Object templates<br />
** The current SNMP discovery functionality covers two core areas - interfaces and attributes. If an object is modular, the number and type of interfaces may vary. Some objects are static, such as non-stackable switches. Using a template for static devices would ease the process of adding them, especially in cases where there is no SNMP support in RackTables.<br />
** There are also cases where SNMP-derived information isn't necessary. A user may want to add the object in order to document the rackspace allocation and port connections. Documenting port MAC addresses and other attributes such as serial numbers and SW version provides limited or no value. Using a pre-defined template, ports could be added during the object creation process. If desired, SNMP re-discovery could add the missing information at a later date.</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=553FeatureWishlist2013-11-25T19:29:32Z<p>Adoom42: Undo revision 529 by Adoom42 (talk)</p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys (EntityLink, for example)<br />
* Manage plugins from the web interface<br />
** Install/uninstall, enable/disable capability capability<br />
** Install/uninstall features handle DB table creation/destruction</div>Adoom42https://wiki.racktables.org/index.php?title=Gateways&diff=539Gateways2013-11-02T18:29:16Z<p>Adoom42: /* Setting up queryTerminal function */</p>
<hr />
<div>==What are RackTables gateways==<br />
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.<br />
<br />
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.<br />
<br />
RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.<br />
<br />
==List of device breeds==<br />
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:<br />
{| border=1 cellspacing=0 cellpadding=5<br />
| <tt>air12</tt><br />
| Cisco Aironet IOS release 12.x<br />
|-<br />
| <tt>dlink</tt><br />
| D-Link, unknown release<br />
|-<br />
| <tt>eos4</tt><br />
| Arista EOS release 4.x<br />
|-<br />
| <tt>fdry5</tt><br />
| Foundry Networks IronWare release 5.x<br />
|-<br />
| <tt>ftos8</tt><br />
| Force10 FTOS release 8.x<br />
|-<br />
| <tt>ios12</tt><br />
| Cisco Catalyst IOS release 12.x<br />
|-<br />
| <tt>iosxr4</tt><br />
| Cisco XR IOS release 4.2<br />
|-<br />
| <tt>jun10</tt><br />
| Juniper JunOS releases 10, 11 and 12<br />
|-<br />
| <tt>linux</tt><br />
| generic Linux<br />
|-<br />
| <tt>nxos4</tt><br />
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x<br />
|-<br />
| <tt>ros11</tt><br />
| Marvell ROS release 1.1<br />
|-<br />
| <tt>ucs</tt><br />
| Cisco UCS<br />
|-<br />
| <tt>vrp53</tt><br />
| Huawei VRP release 5.3<br />
|-<br />
| <tt>vrp55</tt><br />
| Huawei VRP releases 5.5 and 5.7<br />
|-<br />
| <tt>xos12</tt><br />
| Extreme Networks XOS release 12<br />
|}<br />
<br />
==List of device commands==<br />
{| border=1 cellspacing=0 cellpadding=5<br />
| <tt>xlatepushq</tt><br />
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.<br />
|-<br />
| <tt>get8021q</tt><br />
| Returns the 802.1Q configuration of the device as a list of arrays.<br />
|-<br />
| <tt>getallconf</tt><br />
| Returns the device's current configuration as a string in native plain-text format (multiline).<br />
|-<br />
| <tt>getcdpstatus</tt><br />
| Returns the list of CDP neighbors as an array.<br />
|-<br />
| <tt>getlldpstatus</tt><br />
| Returns the list of LLDP neighbors as an array.<br />
|-<br />
| <tt>getmaclist</tt><br />
| Returns the MAC address table as an array.<br />
|-<br />
| <tt>getportstatus</tt><br />
| Returns the full list of network interfaces as an array.<br />
|-<br />
| <tt>getinventory</tt><br />
| Returns a list of hardware components as an array.<br />
|}<br />
==Implementation matrix==<br />
{| border=1 cellspacing=0 cellpadding=5<br />
|<br />
| <tt>xlatepushq</tt><br />
| <tt>get8021q</tt><br />
| <tt>getallconf</tt><br />
| <tt>getcdpstatus</tt><br />
| <tt>getlldpstatus</tt><br />
| <tt>getmaclist</tt><br />
| <tt>getportstatus</tt><br />
| <tt>getinventory</tt><br />
|-<br />
| <tt>air12</tt><br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>dlink</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>eos4</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>fdry5</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>ftos8</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>ios12</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>iosxr4</tt><br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>jun10</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>linux</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>nxos4</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>ros11</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>ucs</tt><br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
| <br />
| bgcolor=green |<br />
|-<br />
| <tt>vrp53</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>vrp55</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>xos12</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
|}<br />
<br />
==File layout==<br />
The gateways part consist of two file sets:<br />
* PHP files stored in wwwroot/inc/ dir:<br />
*; <tt>deviceconfig.php</tt><br />
*: 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.<br />
*; <tt>remote.php</tt><br />
*: The current 0.20.x gateways API. This file normally requires no changes.<br />
*; <tt style="text-decoration: line-through">gateways.php</tt><br />
*: 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<br />
<br />
* CLI tools stored in gateways/ dir:<br />
*; <tt>netcat ssh sshnokey telnet ucssdk</tt><br />
*: CLI-mode clients providing a particular communication protocol. <br />
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt><br />
*: Old-style CLI tools. Removed in 0.20.2.<br />
;<br />
<br />
==Key API functions==<br />
There are two core functions:<br />
<pre><br />
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)<br />
function callScript ($gwname, $params, $in, &$out, &$errors)<br />
</pre><br />
<br />
== Setting up queryTerminal function ==<br />
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.<br />
It takes care of the communication protocol, connection properties and credentials for each object_id.<br />
To do so, it must be set up properly. It calls the user-defined callback function '''terminal_settings''' to <br />
collect the parameters. This function is responsible for overriding of connection properties based on <br />
local policy. Most of the re-definable parameters have reasonable default values, but username and<br />
password must be specifyed in any case.<br />
<br />
Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':<br />
<pre><br />
$params = array (array<br />
(<br />
'hostname' => $endpoints[0], // either hostname or IP<br />
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'<br />
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'<br />
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables<br />
'username' => NULL,<br />
'password' => NULL,<br />
'timeout' => 15,<br />
'connect_timeout' => 2,<br />
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'<br />
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u<br />
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.<br />
));<br />
</pre><br />
<br />
Typical implementation of this user-defined callback looks like this:<br />
<br />
<pre><br />
function terminal_settings ($cell, $params)<br />
{<br />
// servers and Juniper routers use ssh, other - telnet<br />
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))<br />
{<br />
$params[0]['protocol'] = 'ssh';<br />
$params[0]['proto'] = '4';<br />
$params[0]['sudo_user'] = 'racktables';<br />
$params[0]['connect_timeout'] = 5;<br />
}<br />
else<br />
{<br />
$params[0]['protocol'] = 'telnet';<br />
$params[0]['username'] = 'username';<br />
$params[0]['password'] = 'password';<br />
$params[0]['timeout'] = 30;<br />
}<br />
}<br />
</pre><br />
<br />
You can put your definition of terminal_settings function into your secret.php file.</div>Adoom42https://wiki.racktables.org/index.php?title=Gateways&diff=537Gateways2013-11-02T18:27:26Z<p>Adoom42: /* Key API funcrions */</p>
<hr />
<div>==What are RackTables gateways==<br />
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.<br />
<br />
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.<br />
<br />
RackTables has unified API function to work with these clients: '''[[#Setting_up_queryTerminal_function|queryTerminal]]'''. It decides which gateway and which connection parameters to use based on user-defined callback function results.<br />
<br />
==List of device breeds==<br />
In RackTables source code a '''breed''' stands for a distinguished type of a managed device. There are currently the following breeds implemented:<br />
{| border=1 cellspacing=0 cellpadding=5<br />
| <tt>air12</tt><br />
| Cisco Aironet IOS release 12.x<br />
|-<br />
| <tt>dlink</tt><br />
| D-Link, unknown release<br />
|-<br />
| <tt>eos4</tt><br />
| Arista EOS release 4.x<br />
|-<br />
| <tt>fdry5</tt><br />
| Foundry Networks IronWare release 5.x<br />
|-<br />
| <tt>ftos8</tt><br />
| Force10 FTOS release 8.x<br />
|-<br />
| <tt>ios12</tt><br />
| Cisco Catalyst IOS release 12.x<br />
|-<br />
| <tt>iosxr4</tt><br />
| Cisco XR IOS release 4.2<br />
|-<br />
| <tt>jun10</tt><br />
| Juniper JunOS releases 10, 11 and 12<br />
|-<br />
| <tt>linux</tt><br />
| generic Linux<br />
|-<br />
| <tt>nxos4</tt><br />
| Cisco Nexus NX-OS releases 4.x, 5.x and 6.x<br />
|-<br />
| <tt>ros11</tt><br />
| Marvell ROS release 1.1<br />
|-<br />
| <tt>ucs</tt><br />
| Cisco UCS<br />
|-<br />
| <tt>vrp53</tt><br />
| Huawei VRP release 5.3<br />
|-<br />
| <tt>vrp55</tt><br />
| Huawei VRP releases 5.5 and 5.7<br />
|-<br />
| <tt>xos12</tt><br />
| Extreme Networks XOS release 12<br />
|}<br />
<br />
==List of device commands==<br />
{| border=1 cellspacing=0 cellpadding=5<br />
| <tt>xlatepushq</tt><br />
| Translates a given array of breed-independent operations into a multiline string with breed-specific commands.<br />
|-<br />
| <tt>get8021q</tt><br />
| Returns the 802.1Q configuration of the device as a list of arrays.<br />
|-<br />
| <tt>getallconf</tt><br />
| Returns the device's current configuration as a string in native plain-text format (multiline).<br />
|-<br />
| <tt>getcdpstatus</tt><br />
| Returns the list of CDP neighbors as an array.<br />
|-<br />
| <tt>getlldpstatus</tt><br />
| Returns the list of LLDP neighbors as an array.<br />
|-<br />
| <tt>getmaclist</tt><br />
| Returns the MAC address table as an array.<br />
|-<br />
| <tt>getportstatus</tt><br />
| Returns the full list of network interfaces as an array.<br />
|-<br />
| <tt>getinventory</tt><br />
| Returns a list of hardware components as an array.<br />
|}<br />
==Implementation matrix==<br />
{| border=1 cellspacing=0 cellpadding=5<br />
|<br />
| <tt>xlatepushq</tt><br />
| <tt>get8021q</tt><br />
| <tt>getallconf</tt><br />
| <tt>getcdpstatus</tt><br />
| <tt>getlldpstatus</tt><br />
| <tt>getmaclist</tt><br />
| <tt>getportstatus</tt><br />
| <tt>getinventory</tt><br />
|-<br />
| <tt>air12</tt><br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>dlink</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>eos4</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>fdry5</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>ftos8</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>ios12</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>iosxr4</tt><br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>jun10</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
|-<br />
| <tt>linux</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>nxos4</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>ros11</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>ucs</tt><br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
| <br />
| <br />
| <br />
| bgcolor=green |<br />
|-<br />
| <tt>vrp53</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>vrp55</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
|-<br />
| <tt>xos12</tt><br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| bgcolor=green |<br />
| <br />
| bgcolor=green |<br />
| <br />
| <br />
| <br />
|}<br />
<br />
==File layout==<br />
The gateways part consist of two file sets:<br />
* PHP files stored in wwwroot/inc/ dir:<br />
*; <tt>deviceconfig.php</tt><br />
*: 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.<br />
*; <tt>remote.php</tt><br />
*: The current 0.20.x gateways API. This file normally requires no changes.<br />
*; <tt style="text-decoration: line-through">gateways.php</tt><br />
*: 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<br />
<br />
* CLI tools stored in gateways/ dir:<br />
*; <tt>netcat ssh sshnokey telnet ucssdk</tt><br />
*: CLI-mode clients providing a particular communication protocol. <br />
*; <tt style="text-decoration: line-through">gateways/sendfile/ gateways/deviceconfig/ gateways/switchvlans/</tt><br />
*: Old-style CLI tools. Removed in 0.20.2.<br />
;<br />
<br />
==Key API functions==<br />
There are two core functions:<br />
<pre><br />
function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)<br />
function callScript ($gwname, $params, $in, &$out, &$errors)<br />
</pre><br />
<br />
== Setting up queryTerminal function ==<br />
Every operation racktables performs on device (except of SNMP walk) is made by calling queryTerminal API function.<br />
It takes care of the communication protocol, connection properties and credentials for each object_id.<br />
To do so, it must be setted up properly. It calls user-defined callback function '''terminal_settings''' to <br />
collect the parameters. This function is responsible for overriding of connection properties based on <br />
local policy. Most of the re-definable parameters have reasonable default values, but username and<br />
password must be specifyed in any case.<br />
<br />
Here is a full schema of $params array (with default values) which could be changed in '''terminal_settings''':<br />
<pre><br />
$params = array (array<br />
(<br />
'hostname' => $endpoints[0], // either hostname or IP<br />
'protocol' => $protocol, // either 'telnet', 'netcat' or 'ssh'<br />
'port' => NULL, // if NULL, 22 for 'ssh' proto and 23 for 'telnet' and 'netcat'<br />
'prompt' => $prompt, // used only by 'telnet'. There is apropriate default values for each device breed known by RackTables<br />
'username' => NULL,<br />
'password' => NULL,<br />
'timeout' => 15,<br />
'connect_timeout' => 2,<br />
'prompt_delay' => 0.001, // 1ms. Used only by 'telnet'<br />
'sudo_user' => NULL, // used only by 'ssh'. If specified, ssh gateway calls itself with sudo -u<br />
'identity_file' => NULL, // used only by 'ssh'. Path to secret key file.<br />
));<br />
</pre><br />
<br />
Typical implementation of this user-defined callback looks like this:<br />
<br />
<pre><br />
function terminal_settings ($cell, $params)<br />
{<br />
// servers and Juniper routers use ssh, other - telnet<br />
if (considerGivenConstraint ($cell, '{$typeid_4} or {Juniper}'))<br />
{<br />
$params[0]['protocol'] = 'ssh';<br />
$params[0]['proto'] = '4';<br />
$params[0]['sudo_user'] = 'racktables';<br />
$params[0]['connect_timeout'] = 5;<br />
}<br />
else<br />
{<br />
$params[0]['protocol'] = 'telnet';<br />
$params[0]['username'] = 'username';<br />
$params[0]['password'] = 'password';<br />
$params[0]['timeout'] = 30;<br />
}<br />
}<br />
</pre><br />
<br />
You can put your definition of terminal_settings function into your secret.php file.</div>Adoom42https://wiki.racktables.org/index.php?title=Main_Page&diff=535Main Page2013-10-27T20:48:43Z<p>Adoom42: add SSL link</p>
<hr />
<div>[[File:RackTables-development-roadmap-2012Q3.png|391px|thumb|right]]<br />
* for RackTables users<br />
** [[RackTablesInstallHowto | Installation HOWTO]]<br />
** [[RackTablesAdminGuide | Administrator's guide]]<br />
** [[RackTablesUserGuide | User's guide]]<br />
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)<br />
** [[FAQ]]<br />
** [[LDAP | LDAP authentication]]<br />
** [[SAML | SAML authentication]]<br />
* for RackTables hackers<br />
** [[SourceCode | Working with RackTables source code]]<br />
** [[RackTablesDevelGuide | Developer's guide]]<br />
** [[FeatureWishlist | Feature wishlist]]<br />
** [[Gateways | Extending RackTables with gateways]]<br />
* for development team<br />
** [[NewRelease | Checklist and procedures to make a new release]]<br />
** [[ProjectInfrastructure | Project infrastructure]]<br />
** [[Roadmap]]<br />
<br />
<br />
To use this site over an SSL connection, visit [https://wiki.racktables.org/ https://wiki.racktables.org/]<br />
<br />
Note that a self-signed certificate is used.</div>Adoom42https://wiki.racktables.org/index.php?title=RackTablesDevelGuide&diff=531RackTablesDevelGuide2013-10-26T21:18:09Z<p>Adoom42: /* Overview */</p>
<hr />
<div>[[File:RackTables-development-roadmap-2012Q3.png|391px|thumb|right]]<br />
= Config options =<br />
Variables are stored in the Config SQL table:<br />
<pre><br />
mysql> DESCRIBE Config;<br />
+----------------+-----------------------+------+-----+---------+-------+<br />
| Field | Type | Null | Key | Default | Extra |<br />
+----------------+-----------------------+------+-----+---------+-------+<br />
| varname | char(32) | NO | PRI | NULL | |<br />
| varvalue | char(255) | NO | | NULL | |<br />
| vartype | enum('string','uint') | NO | | string | |<br />
| emptyok | enum('yes','no') | NO | | no | |<br />
| is_hidden | enum('yes','no') | NO | | yes | |<br />
| is_userdefined | enum('yes','no') | NO | | no | |<br />
| description | text | YES | | NULL | |<br />
+----------------+-----------------------+------+-----+---------+-------+<br />
7 rows in set (0.00 sec)<br />
</pre><br />
Options are read and written with getConfigVar() and setConfigVar() functions respectively. The current naming convention for new options is to use descriptive expressions in ALL_CAPITAL_LETTERS with spaces REPLACED_WITH_UNDERSCORES. When adding a new option, check the following places:<br />
# upgrade.php<br />
# install/init-dictbase.sql<br />
# inc/ophandlers.php:resetUIConfig()<br />
Default values must match regardless of the way they were set: initial setup, upgrade or UI reset.<br />
<br />
= Exceptions and error handling =<br />
Error handling now can be done by exceptions mechanism. index.php and process.php have been wrapped in <br />
<pre><br />
ob_start(); <br />
try{<br />
...<br />
ob_end_flush();<br />
} catch {<br />
print_error_nicely();<br />
}<br />
</pre><br />
kind of code, so every exception you miss and not catch will be printed instead of the page that had to be printed.<br />
<br />
This saves a lot of code, take a look at a function<br />
<pre><br />
// before<br />
<br />
function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '')<br />
{<br />
if ($chapter_no <= 0)<br />
{<br />
showError ('Invalid args', __FUNCTION__);<br />
die;<br />
}<br />
global $dbxlink;<br />
$query =<br />
"update Dictionary set dict_value = '${dict_value}' where chapter_id=${chapter_no} " .<br />
"and dict_key=${dict_key} limit 1";<br />
$result = $dbxlink->query ($query);<br />
if ($result == NULL)<br />
{<br />
showError ('SQL query failed', __FUNCTION__);<br />
die;<br />
}<br />
return TRUE;<br />
}<br />
<br />
// and after<br />
<br />
function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '')<br />
{<br />
if ($chapter_no <= 0) <br />
throw InvalidArgException('$chapter_no', $chapter_no);<br />
// the function below does not exist<br />
Database::updateWhere(array('dict_value'=>$dict_value), 'Dictionary', array('chapter_id'=>$chapter_no, 'dict_key'=>$dict_key));<br />
return TRUE;<br />
}<br />
</pre><br />
<br />
Function Database::updateWhere throws an exception if query is bad, and you can catch it if you want and handle it as necessary, or you can just ignore it and application will display error message with a stacktrace and such.<br />
<br />
Exceptions registered so far:<br />
<br />
;RackTablesError<br />
:Fatal, final error, usually annotated.<br />
<br />
;RTDatabaseError<br />
:"Soft" database error (UNIQUE/FOREIGN KEY constraint violation or timeout).<br />
<br />
;RTGatewayError<br />
:An external gateway raised an error or the data it returned was corrupt or otherwise invalid.<br />
<br />
;EntityNotFoundException<br />
:Requested record could not be found in the database.<br />
<br />
;InvalidArgException<br />
:At least one of the arguments provided to a function had invalid value, and that value did NOT come from user's input. This means a programming error and cannot be worked around.<br />
<br />
;InvalidRequestArgException<br />
:Ditto, but the value was supplied by the user, and the error should be handled with an "inline" error message.<br />
<br />
;RTBuildLVSConfigError<br />
:LVS keepalived text compilation failed.<br />
----<br />
<br />
= RackCode =<br />
<pre><br />
# identifier<br />
ID ::= ^[[:alnum:]]([\. _~-]?[[:alnum:]])*$<br />
# identifier in brackets<br />
PREDICATE ::= [ID]<br />
DEFINE ::= define PREDICATE<br />
# identifier in curly braces<br />
TAG ::= {ID}<br />
# identifier in curly braces, starting with dollar sign<br />
AUTOTAG ::= {$ID}<br />
# context modifier<br />
CTXMOD ::= clear | insert TAG | remove TAG<br />
# context modifier list<br />
CTXMODLIST ::= CTXMODLIST CTXMOD | CTXMOD<br />
UNARY_EXPRESSION ::= true | false | TAG | AUTOTAG | PREDICATE | (EXPRESSION) | not UNARY_EXPRESSION<br />
# logical AND<br />
AND_EXPRESSION ::= AND_EXPRESSION and UNARY_EXPRESSION | UNARY_EXPRESSION<br />
# logical OR<br />
EXPRESSION ::= EXPRESSION or AND_EXPRESSION | AND_EXPRESSION<br />
GRANT ::= allow EXPRESSION | deny EXPRESSION<br />
DEFINITION ::= DEFINE EXPRESSION<br />
ADJUSTMENT ::= context CTXMODLIST on EXPRESSION<br />
# RackCode permission text<br />
CODETEXT ::= CODETEXT GRANT | CODETEXT DEFINITION | CODETEXT ADJUSTMENT | GRANT | DEFINITION | ADJUSTMENT<br />
</pre><br />
Comments in RackCode last from the first <tt>#</tt> character to the end of current line and are filtered out automatically:<br />
<pre><br />
allow {tech support} # or {admins} <--- note where comment starts<br />
and {assets} # <--- this is still a part of "allow" statement<br />
<br />
deny {guests}<br />
</pre><br />
<br />
= API =<br />
== Hello, World! ==<br />
To enable all RackTables functions and load all necessary system data, it is enough to include one file.<br />
<pre><br />
<?php<br />
<br />
include ('inc/init.php');<br />
// do something<br />
<br />
?><br />
</pre><br />
<br />
There is a special parameter, which tells, if current file is intended to be run by web-server or from a command line. In the latter case neither authentication nor authorization is performed.<br />
<pre><br />
<?php<br />
<br />
$script_mode = TRUE;<br />
include ('inc/init.php');<br />
<br />
echo "I am a crontab script!\n";<br />
// do something<br />
<br />
?><br />
</pre><br />
<br />
== Searching for the appropriate library function ==<br />
The easy way to determine which function does what you need to is analyze how the corresponding web interface request is processed.<br />
<br />
Each modification through web causes HTTP POST request being sent with at least these base parameters: 'page', 'tab', 'op'.<br />
There is the $ophandler array in wwwroot/inc/navigation.php filled with function names for each triplet of base web operation parameters.<br />
<br />
Then, when you determine the handler function name for you operation (like object creating), you could examine its code in wwwroot/inc/ophandlers.php. It usually calls appropriate functions from database.php.<br />
<br />
Also, there are some trivial operations which have no special ophandler function. Then the universal database wrapper called tableHandler takes place. It makes direct SQL queries, building them by $opspec_list array data.<br />
<br />
<br />
== Realms ==<br />
There are several principal realms in !RackTables database. Any realm contains zero, one or more records. Each such record is addressed by its ID (primary key).<br />
<br />
;object<br />
:All servers, switches, UPSes, wireless, cable management and any other stuff, which is viewed and managed on the main "Objects" page.<br />
;ipv4net<br />
:all IPv4 networks<br />
;ipv6net<br />
:all IPv6 networks<br />
;user<br />
:All local accounts. There is at least one local account in any RackTables system (admin). There may be more.<br />
;rack<br />
:All racks.<br />
;file<br />
:All files.<br />
;ipv4vs<br />
:All IPv4 virtual services.<br />
;ipv4rspool<br />
:All IPv4 real server pools.<br />
<br />
== function scanRealmByText ($realm, $ftext = "") ==<br />
;realm<br />
:String equal to one of the realms shown above.<br />
;ftext<br />
:Optional filter text. If this text is empty, all records of the realm are returned. If it is not empty, it is interpreted as a !RackCode expression. This expression is then evaluated against each record of the realm and only those records, for which the filter returned TRUE, are returned.<br />
<br />
<pre><br />
<?php<br />
<br />
include ('inc/init.php');<br />
<br />
$allusers = scanRealmByText ('user');<br />
$smallnetworks = scanRealmByText ('ipv4net', '{small network}');<br />
$unmounted_objects = scanRealmByText ('object', '{$unmounted}');<br />
<br />
?><br />
</pre><br />
<br />
== function spotEntity ($realm, $id) ==<br />
This is the right function to get information about some record, for which you know where it belongs to and what its key value is. If this information isn't available, it has to be discovered somehow first.<br />
<br />
;realm<br />
:Realm name.<br />
;id<br />
:Record number (key value, ID...).<br />
<br />
<pre><br />
<?php<br />
<br />
include ('inc/init.php');<br />
<br />
$adminuser = spotEntity ('user', 1); // Admin account is always number 1.<br />
$myspecialfile = spotEntity ('file', 12345);<br />
$serverinfo = spotEntity ('object', 67890);<br />
<br />
?><br />
</pre><br />
<br />
== function amplifyCell (&$record, $dummy = NULL) ==<br />
It is assumed, that spotEntity() loads only basic data about the record requested. "Basic" means enough for renderCell() to do its job or to render a row in a table. To get detailed information about the "cell" it is necessary to execute amplifyCell() on it:<br />
<pre><br />
<?php<br />
include ('inc/init.php');<br />
<br />
$adminuser = spotEntity ('user', 1); // Admin account is always number 1.<br />
amplifyCell ($adminuser);<br />
<br />
$unmounted_objects = scanRealmByText ('object', '{$unmounted}');<br />
array_walk ($unmounted_objects, 'amplifyCell');<br />
?><br />
</pre><br />
<br />
== function renderCell ($cell) ==<br />
Render cell structure as a rectangular block with icon, name, tags and other information. Available since 0.17.2.<br />
<br />
= Dictionary =<br />
== Where the data is ==<br />
Since release 0.17.2 all records are stored in file <tt>inc/dictionary.php</tt>:<br />
<pre><br />
$dictionary = array<br />
(<br />
1 => array ('chapter_id' => 1, 'dict_value' => 'BlackBox'),<br />
2 => array ('chapter_id' => 1, 'dict_value' => 'PDU'),<br />
3 => array ('chapter_id' => 1, 'dict_value' => 'Shelf'),<br />
4 => array ('chapter_id' => 1, 'dict_value' => 'Server'),<br />
5 => array ('chapter_id' => 1, 'dict_value' => 'DiskArray'),<br />
6 => array ('chapter_id' => 1, 'dict_value' => 'TapeLibrary'),<br />
7 => array ('chapter_id' => 1, 'dict_value' => 'Router'),<br />
8 => array ('chapter_id' => 1, 'dict_value' => 'Network switch'),<br />
9 => array ('chapter_id' => 1, 'dict_value' => 'PatchPanel'),<br />
10 => array ('chapter_id' => 1, 'dict_value' => 'CableOrganizer'),<br />
11 => array ('chapter_id' => 1, 'dict_value' => 'spacer'),<br />
12 => array ('chapter_id' => 1, 'dict_value' => 'UPS'),<br />
[...]<br />
</pre><br />
<br />
== meaning of chapter ID ==<br />
<pre><br />
mysql> SELECT * FROM Chapter;<br />
+----+--------+-----------------------------+<br />
| id | sticky | name |<br />
+----+--------+-----------------------------+<br />
| 1 | yes | RackObjectType | <br />
| 2 | yes | PortType | <br />
| 11 | no | server models | <br />
| 12 | no | network switch models | <br />
| 13 | no | server OS type | <br />
| 14 | no | switch OS type | <br />
| 16 | no | router OS type | <br />
| 17 | no | router models | <br />
| 18 | no | disk array models | <br />
| 19 | no | tape library models | <br />
| 21 | no | KVM switch models | <br />
| 22 | no | multiplexer models | <br />
| 23 | no | console models | <br />
| 24 | no | network security models | <br />
| 25 | no | wireless models | <br />
| 26 | no | fibre channel switch models | <br />
| 27 | no | PDU models | <br />
+----+--------+-----------------------------+<br />
17 rows in set (0.00 sec)<br />
</pre><br />
<br />
== wikilinks ==<br />
It is possible to render a record as an URL:<br />
<pre>[[ something | http://somewhere/ ]]</pre><br />
However, it is up to the editor, if to include URL into description or not. URLs can be added, changed and removed from particular records later, if it makes sense.<br />
<br />
== G-markers ==<br />
Text before the marker is always used for OPTGROUP in SELECT element. The difference is in the way the text is rendered as a plain text or a clickable URL. GSKIP makes OPTGROUP name to be skipped. GPASS passes OPTGROUP name on the text:<br />
<pre><br />
719 => array ('chapter_id' => 24, 'dict_value' => '[[Cisco%GPASS%ASR 1006 | http://cisco.com/en/US/products/ps9438/index.html]]'),<br />
720 => array ('chapter_id' => 13, 'dict_value' => '[[BSD%GSKIP%OpenBSD 3.3 | http://openbsd.org/33.html]]'),<br />
</pre><br />
<br />
[[Image:dictionary-G-markers.png]]<br />
<br />
= Customizing =<br />
== Overriding the search procedure ==<br />
<br />
RackTables contains API allowing to customize search. Two ways of customizing <br />
are available:<br />
<br />
a) You could change text request (search terms) before passing it to standard search procedure;<br />
<br />
b) You could either modify the search results list returned by the standard search procedure, or fill that list completely by yourself.<br />
<br />
Of course, you can combine the methods above.<br />
<br />
First, you need Racktables to include your code. Racktables tries to include <br />
the user's php lib called "wwwroot/inc/local.php". To be honest, the actual<br />
include path is "$path_to_local_php", which by default equals to <br />
"$racktables_confdir . '/local.php'". $racktables_confdir, consequently, by default<br />
is the dir where the library files are stored (wwwroot/inc). You could override<br />
either of these paths by making separate entry point (custom index.php), or in <br />
secret.php. If you want to actively use plugin model, you may want to write a<br />
generic local.php scanning your custom plugins directory and including files from<br />
it. This technique will allow you install plugins by simply putting them into this dir,<br />
and to easily exchange plugins with the community.<br />
<br />
So, you've decided to store your local.php in the default location and override<br />
the search procedure. Lets take an example. We want to take a URL in search box,<br />
extract hostname from it, resolve it into an IP address and than display the search<br />
results for this address. Proper local.php is below:<br />
<pre><br />
<?php<br />
//step 1<br />
$page['search']['handler'] = 'searchHandler_Local';<br />
<br />
function searchHandler_Local ()<br />
{<br />
// step 2<br />
$terms = trim ($_REQUEST['q']);<br />
<br />
// step 3<br />
if (preg_match("/^(http:\/\/)/", $terms))<br />
{ // Search by IP if URL was given<br />
preg_match("/^(http:\/\/)?([^\/]+)/i", $terms, $matches);<br />
$terms = gethostbyname($matches[2]);<br />
}<br />
<br />
// step 4 <br />
$results = searchEntitiesByText ($terms);<br />
<br />
// step 5<br />
// modify the $results you need to<br />
<br />
// step 6<br />
renderSearchResults ($terms, $results);<br />
}<br />
<br />
?><br />
</pre><br />
<br />
Let's describe this simple script step-by step.<br />
<br />
Step 1. First we overwrite the search handler procedure name, replacing the standard one<br />
by the custom 'searchHandler_Local'. Please note that you can not chain overrides - <br />
as soon you set procedure name in $page['search']['handler'] (as well as any other <br />
handler) the old handler is forgotten, and the new one is responsible for calling it,<br />
if it decides to.<br />
<br />
Step 2. We need to retrieve the search request. It is passed in 'q' HTTP GET parameter to<br />
the search handler.<br />
<br />
Step 3. We rewrite the search request text replacing URL to the corresponding IP address.<br />
It is an example of using the way (a) of customizing RackTables search (see above)<br />
<br />
Step 4. Let the standard search procedure do its job. We call searchEntitiesByText for that.<br />
<br />
Step 5. Here you could change the results returned by standard function. This array structure<br />
is pretty complex, you may want to examine it by calling var_dump. The array is indexed by<br />
search method (like 'object' or 'ipv6addressbydescr'). The rest structure depends of the first<br />
key value. If you want to display your very own search results section, you could add the unknown<br />
key into this array which will be used as a header for this results section. The HTML code for its<br />
body will be the value of $results by the given key.<br />
<br />
Step 6. Display the search results using renderSearchResults standard function.<br />
<br />
== Adding a custom report ==<br />
There is a simple way to write custom reports and embed them into the RackTables user interface.<br />
<br />
All you need to do is write a report rendering function, apparently using such RackTables API functions<br />
like scanRealmByText, spotEntity and renderCell, and register this function as a report rendering handler.<br />
This example should make it clear:<br />
<br />
1. Save the code below into the plugins/test-report.php file:<br />
<pre><br />
<?php<br />
<br />
$tabhandler['reports']['test'] = 'renderTestReport'; // register a report rendering function<br />
$tab['reports']['test'] = 'Test Report'; // title of the report tab<br />
<br />
function renderTestReport()<br />
{<br />
// fill the HW type stat array<br />
$stat = array();<br />
$total = 0;<br />
$filter = '{switch} and {Moscow}';<br />
foreach (scanRealmByText ('object', $filter) as $switch)<br />
{<br />
$attributes = getAttrValues ($switch['id']);<br />
if (isset ($attributes[2]))<br />
{<br />
$attr = $attributes[2];<br />
if (! isset ($stat[$attr['key']]))<br />
$stat[$attr['key']] = array<br />
(<br />
'value' => $attr['a_value'],<br />
'count' => 0,<br />
);<br />
++$stat[$attr['key']]['count'];<br />
++$total;<br />
}<br />
}<br />
<br />
// display the stat array<br />
echo "<h2>Moscow switches HW types report ($total)</h2><ul>";<br />
foreach ($stat as $type_id => $type)<br />
{<br />
$type_filter = $filter . ' and {$attr_2_' . $type_id . '}';<br />
$link = '<a href="' . makeHref (array ('page' => 'depot', 'cfe' => $type_filter)) . '">' . $type['count'] . ' devices</a>';<br />
echo "<li>${type['value']} - $link</li>";<br />
}<br />
echo '</ul>';<br />
}<br />
<br />
?><br />
</pre><br />
<br />
2. To install your report into RackTables, place the file in the plugins directory.<br />
<br />
This report displays switch devices located in Moscow, grouped by their hardware model types. Each line of output contains the device count of corresponding model and a link to view the device list, like this:<br />
<pre><br />
Moscow switches HW types report (2)<br />
* Cisco Catalyst 2960G-24PC - <a>1 devices</a><br />
* Cisco Catalyst 2960G-24TC - <a>1 devices</a><br />
</pre><br />
<br />
= 802.1Q internals =<br />
== execution of "pull-only" and "pull+push" sync requests ==<br />
[[Image:RackTables-8021Q-sync.png]]<br />
<br />
<br />
= SNMP sync =<br />
== Overview ==<br />
The feature evolved as a procedure intended to be run once for any given device. The main procedure is built around the ifTable SNMP tree, which belongs to IF-MIB (very old and ubiquitous one). With regard to network switches, everything is done in the doSwitchSNMPmining() function, located in inc/snmp.php.<br />
<br />
The device is polled using the FQDN (hostname or IP/IPv6) attribute, if set. If not, assigned IP addresses will be polled.<br />
<br />
First, subsets of ifTable are taken and combined in a way to produce a PHP array of all interfaces (with MAC address info for each interface).<br />
<br />
Then, for each item in the interface list, a "processor" is tried from the list of processors (which is known for each supported product number, that is, SNMP OID). This way, there is a list of "processor" items and a list of known switches, where each item uses one or more processors to process the list of interfaces. There is also a vendor-specific procedure for things like serial number or console port type.<br />
<br />
Each processor is built as follows:<br />
* 'pattern' stands for PCRE pattern, which is tried against interface name (ifDescr in SNMP).<br />
* 'replacement' is a PCRE replacement for it (most often interface names need to be compressed into something of reasonable length, e.g. 'GigabitEthernet1/2/3' -> 'gi1/2/3').<br />
* 'label' stands for port's visible label ('replacement' was for port's interface name, i.e. the one which switch's operating system uses) in SQL it is Port.label.<br />
* 'dict_key' stands for a special value which can be defined in one of two forms: either "N2" or "N1-N2" (in the former case N1 is taken to be equal to 1).<br />
<br />
N1 stands for IIF ID, its valid values are stored in the PortInnerInterface table.<br />
N2 stands for OIF ID, its values are stored in Dictionary chapter 2.<br />
<br />
For example, the most popular interface, "hardwired 1000Base-T" may be written as either 24 or '1-24'.<br />
For an "empty XENPAK" port, use '5-1079'.<br />
IIF stands for "Inner InterFace" and OIF stands for "Outer InterFace"<br />
In the Port table, IIF ID is stored in the "iif_id" column and OIF ID in the "type" column.<br />
this way the description of "dict_key" in a processor item<br />
<br />
The 'known_switches' array is used to map processors and other information to specific switch models.<br />
* 'dict_key' is the dictionary ID which represents the switch model. The list of known models is defined in dictionary.php.<br />
* 'text' is a basic description of the device that is presented to the user after discovery is complete.<br />
* 'processors' lists which processors are applied to the device.<br />
* 'ifDescrOID' is an optional attribute used in cases where the SNMP ifDescr data does not include unique values (e.g. all interfaces are named 'Ethernet Interface'). It specifies the name of the table which does indeed contain unique interface names.<br />
* 'try_next_proc' controls the way different processors are applied. It only refers to if the PCRE pattern has matched or not. In the case of TRUE, the port is created as prescribed and processing of the current interface goes on with the next processor item. In the case of FALSE, the port is added and no more processor items are tried for the current interface (procedure goes on to the next interface).<br />
<br />
When it comes to adding support for another switch, the best route is to study the device to find out which physical ports it has and how they are represented in SNMP. In particular, 'try_next_proc' is used for combo ports (ones allowing either copper or SFP media under the same OS interface). The work is much easier when some other device from the same product line already exists in snmp.php. Some product lines only have different OIDs and dict_key values, while everything else is the same (e.g. a switch which has PoE ports and one which does not).<br />
<br />
=== Environmental requirements ===<br />
This function uses symbolic OIDs to access the devices which in turn requires base MIBs to be installed and configured properly. If they're not you'll get ''"Fatal SNMP error"'' on the webpage and ''"PHP Warning: snmp2_get(): Invalid object identifier: sysObjectID.0 in /var/www/rt/inc/snmp.php"'' in the webserver error log.<br />
<br />
In case of ''Debian GNU/Linux'' (squeeze and up), for example, this means that apart from <tt>php5-snmp</tt> there must be <tt>snmp-mibs-downloader</tt> installed, the MIBs downloaded and <tt>/etc/snmp/snmp.conf</tt> edited to allow their use. Do not forget to restart php (apache) after the changes.<br />
<br />
== Example 1: Arista 7124S ==<br />
This is a switch which has 24 SFP+ ports, two management ports and one power supply.<br />
<br />
SNMP returns the following names for the ifDescr table:<br />
* Ethernet1<br />
* Ethernet2<br />
* ...<br />
* Ethernet24<br />
* Management1<br />
* Management2<br />
<br />
Add to dictionary.php:<br />
<pre><br />
1610 => array ('chapter_id' => 12, 'dict_value' => 'Arista%GPASS%7124S'),<br />
</pre><br />
<br />
Add to snmp.php:<br />
<pre><br />
$iftable_processors['arista-any-SFP+'] = array<br />
(<br />
'pattern' => '@^Ethernet([[:digit:]]+)$@',<br />
'replacement' => '\\1',<br />
'dict_key' => '9-1084',<br />
'label' => '\\1',<br />
'try_next_proc' => FALSE,<br />
);<br />
<br />
$iftable_processors['arista-management'] = array<br />
(<br />
'pattern' => '@^Management(1|2)$@',<br />
'replacement' => 'mgmt\\1',<br />
'dict_key' => '1-24',<br />
'label' => 'Management',<br />
'try_next_proc' => FALSE,<br />
);<br />
</pre><br />
<br />
<pre><br />
'30065.1.3011.7124.3282' => array<br />
(<br />
'dict_key' => 1610,<br />
'text' => 'DCS-7124S: 24 SFP+/10000',<br />
'processors' => array ('arista-any-SFP+', 'arista-management'),<br />
),<br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=529FeatureWishlist2013-10-19T22:26:43Z<p>Adoom42: port tracing was added to 0.20.6</p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys (EntityLink, for example)<br />
* Manage plugins from the web interface<br />
** Install/uninstall, enable/disable capability capability<br />
** Install/uninstall features handle DB table creation/destruction</div>Adoom42https://wiki.racktables.org/index.php?title=FAQ&diff=525FAQ2013-09-23T14:59:49Z<p>Adoom42: /* Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) */</p>
<hr />
<div>= RackTables FAQ =<br />
<br />
== How do I edit this wiki? ==<br />
Send a message to devteam@racktables.org.<br />
<br />
== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==<br />
RackTables only supports some specific switch models, and yours is not one of them. <br />
<br />
There are two ways to add support for new switch models. Both involve [http://bugs.racktables.org/bug_report_page.php filing a Mantis ticket].<br />
=== Write a patch yourself. ===<br />
* Review [[RackTablesDevelGuide#SNMP_sync|SNMP sync]] for background information.<br />
* Attach the patch to the Mantis ticket.<br />
=== Ask the developers to write a patch for you. ===<br />
The following information is necessary.<br />
* The exact model/part number of the device.<br />
* For a device which features SFP (GBIC, X2 etc) pluggable ports, specify which of these pluggable ports are "combo" (IOW, alternate socket for a copper port under the same name) and which are standalone ports.<br />
If possible, add the following information:<br />
* Manufacturer's markup of device's ports (this can be "21, 22, 23, 24", "21X, 22X, 23X, 24X" or even "21, 22, 23C, 23F, 24C, 24F")<br />
* Dump of SNMP info:<br />
<pre><br />
snmpwalk -v 1 -c public switchname sysDescr.0<br />
snmpwalk -v 1 -c public switchname sysObjectID.0<br />
snmpwalk -v 1 -c public switchname ifTable<br />
</pre><br />
If the device is modular or stackable, also walk ENTITY-MIB:<br />
<pre><br />
snmpwalk -v 1 -c public switchname .1.3.6.1.2.1.47<br />
</pre><br />
<br />
Attach the information to the Mantis ticket. Do not post it inline, as it consumes too much screen real estate.<br />
<br />
== Rack thumb images are broken ==<br />
There are two common reasons for this:<br />
# A mis-formatted local.php extension file. For images to work correctly, every PHP file of your RackTables, which begins with '''<?php''' tag, CAN NOT have a newline before the tag. Every PHP file of your RackTables, which ends with '''?>''' tag, CAN NOT have a newline after the tag.<br />
# GD library is not working (although it probably was at the time of installation). This can be confirmed by means of phpinfo() and fixed with the help of package manager of your server and RackTables README file.<br />
<br />
== How do I browse objects by object type? ==<br />
FILL ME IN<br />
<br />
== How do I handle blade systems/modular switches? ==<br />
You can have one object represent the chassis, and other objects represent the blades. See the documentation on [[RackTablesUserGuide#Containers|Containers]] for details.<br />
<br />
== How do I re-order racks in a row? ==<br />
In versions prior to 0.20, RackTables sorts in alphabetical order. A work-around is to prefix each rack's name with a number:<br />
* "01 F14"<br />
* "02 E14"<br />
* "03 D14"<br />
* "04 C14"<br />
* "05 B14"<br />
* "06 A14"<br />
<br />
Starting with 0.20, you can manually sort racks. View the row, then click the "Manage racks" tab.<br />
<br />
== How do I log out (and log in after that?) ==<br />
To log out: Use the "Click here to logout" link. When presented with the username/password prompt, do not enter anything. Instead, press "Cancel".<br />
<br />
To log in: Press your browser's "back" button to return to any of the normal pages (without "index.php?logout" in the URL) and enter your username/password.<br />
<br />
== How do I enable IPv4 for object type X? ==<br />
Answered by Ray Robertson:<br />
<pre><br />
Configuration --> User Interface --> Change<br />
<br />
Edit the entry for 'List source: IPv4-enabled objects'<br />
<br />
e.g.<br />
List source: IPv4-enabled objects {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798}<br />
<br />
To determine an object's typeid, hover your mouse pointer over the 'Object type' field when viewing the object. The typeid will be revealed in the URL.<br />
</pre><br />
<br />
<br />
'''Scenario:''' <br />
<br />
At Company X you have a proprietary transceiver-type device that is network accessible & can be assigned an IP. You add a new RackObjectType called "Transceiver". To add the IPv4 tab to new "Transceiver" objects, do the following.<br />
<br />
<pre><br />
1. Navigate to Main > Configuration > Dictionary > RackObjectType.<br />
<br />
2. Mouse-over the new RackObjectType you created, in this case "Transceiver". In this example, the Transceiver typeid is 50012.<br />
<br />
3. Now navigate to Main > Configuration > User Interface > Change.<br />
<br />
4. Scroll down to the item/entry "List source: IPv4-enabled objects". <br />
<br />
5. Now go to the end of the line, and enter "or {$typeid_50012}". <br />
<br />
6. Your new line looks like: {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798} or {$typeid_50012}<br />
<br />
7. Save changes.<br />
<br />
8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.<br />
</pre><br />
==How do I decode the IPv4 addresses stored in RackTables MySQL database?==<br />
RackTables stores all IPv4 addresses in their natural representation (32-bit unsigned integers like 180879936). The most reliable way is to use RackTables PHP function spotEntity(), which will return a structure filled with assorted fields, including a dotted-quad representation of IP address. If for whatever reason you decide to fetch the data directly from MySQL database, the simplest way of converting the intergers to dotted-quad (10.200.2.64) form and back is to use MySQL's functions INET_NTOA() and INET_ATON() respectively:<br />
<pre><br />
mysql> SELECT ip, INET_NTOA(ip), mask FROM IPv4Network;<br />
+-----------+---------------+------+<br />
| ip | INET_NTOA(ip) | mask |<br />
+-----------+---------------+------+<br />
| 180879360 | 10.200.0.0 | 31 |<br />
| 180879362 | 10.200.0.2 | 31 |<br />
| 180879364 | 10.200.0.4 | 31 |<br />
| 180879366 | 10.200.0.6 | 31 |<br />
| 180879616 | 10.200.1.0 | 26 |<br />
| 180879680 | 10.200.1.64 | 26 |<br />
| 180879872 | 10.200.2.0 | 26 |<br />
| 180879936 | 10.200.2.64 | 26 |<br />
| 180880192 | 10.200.3.64 | 26 |<br />
| 180880384 | 10.200.4.0 | 26 |<br />
| 180880448 | 10.200.4.64 | 26 |<br />
+-----------+---------------+------+<br />
11 rows in set (0.00 sec)<br />
</pre><br />
==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==<br />
This is a known issue. The workaround is to upgrade from 0.17.x to 0.18.7, then to 0.19.x. Release 0.18.7 can be downloaded directly from the git repository: https://github.com/RackTables/racktables/zipball/RackTables-0.18.7<br />
<br />
==How do I manage tags on a series of objects (networks etc) automaticaly?==<br />
<pre><br />
<?php<br />
<br />
$script_mode = TRUE;<br />
include '/usr/local/racktables/wwwroot/inc/init.php';<br />
<br />
# add tag "right" to each object tagged "left"<br />
$added = getTagByName ('right');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
rebuildTagChainForEntity ('object', $object['id'], array ($added));<br />
<br />
# remove tag "left" from each object tagged "right"<br />
$removed = getTagByName ('left');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
deleteTagForEntity ('object', $object['id'], $removed['id']);<br />
<br />
?><br />
</pre><br />
<br />
= RackTables contributions =<br />
== How can I visualise network topology? ==<br />
See [[Visualisation with GraphViz]] for ideas using GraphViz.</div>Adoom42https://wiki.racktables.org/index.php?title=RackTablesDevelGuide&diff=509RackTablesDevelGuide2013-06-12T15:14:51Z<p>Adoom42: /* Adding a custom report */</p>
<hr />
<div>[[File:RackTables-development-roadmap-2012Q3.png|391px|thumb|right]]<br />
= Config options =<br />
Variables are stored in the Config SQL table:<br />
<pre><br />
mysql> DESCRIBE Config;<br />
+----------------+-----------------------+------+-----+---------+-------+<br />
| Field | Type | Null | Key | Default | Extra |<br />
+----------------+-----------------------+------+-----+---------+-------+<br />
| varname | char(32) | NO | PRI | NULL | |<br />
| varvalue | char(255) | NO | | NULL | |<br />
| vartype | enum('string','uint') | NO | | string | |<br />
| emptyok | enum('yes','no') | NO | | no | |<br />
| is_hidden | enum('yes','no') | NO | | yes | |<br />
| is_userdefined | enum('yes','no') | NO | | no | |<br />
| description | text | YES | | NULL | |<br />
+----------------+-----------------------+------+-----+---------+-------+<br />
7 rows in set (0.00 sec)<br />
</pre><br />
Options are read and written with getConfigVar() and setConfigVar() functions respectively. The current naming convention for new options is to use descriptive expressions in ALL_CAPITAL_LETTERS with spaces REPLACED_WITH_UNDERSCORES. When adding a new option, check the following places:<br />
# upgrade.php<br />
# install/init-dictbase.sql<br />
# inc/ophandlers.php:resetUIConfig()<br />
Default values must match regardless of the way they were set: initial setup, upgrade or UI reset.<br />
<br />
= Exceptions and error handling =<br />
Error handling now can be done by exceptions mechanism. index.php and process.php have been wrapped in <br />
<pre><br />
ob_start(); <br />
try{<br />
...<br />
ob_end_flush();<br />
} catch {<br />
print_error_nicely();<br />
}<br />
</pre><br />
kind of code, so every exception you miss and not catch will be printed instead of the page that had to be printed.<br />
<br />
This saves a lot of code, take a look at a function<br />
<pre><br />
// before<br />
<br />
function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '')<br />
{<br />
if ($chapter_no <= 0)<br />
{<br />
showError ('Invalid args', __FUNCTION__);<br />
die;<br />
}<br />
global $dbxlink;<br />
$query =<br />
"update Dictionary set dict_value = '${dict_value}' where chapter_id=${chapter_no} " .<br />
"and dict_key=${dict_key} limit 1";<br />
$result = $dbxlink->query ($query);<br />
if ($result == NULL)<br />
{<br />
showError ('SQL query failed', __FUNCTION__);<br />
die;<br />
}<br />
return TRUE;<br />
}<br />
<br />
// and after<br />
<br />
function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '')<br />
{<br />
if ($chapter_no <= 0) <br />
throw InvalidArgException('$chapter_no', $chapter_no);<br />
// the function below does not exist<br />
Database::updateWhere(array('dict_value'=>$dict_value), 'Dictionary', array('chapter_id'=>$chapter_no, 'dict_key'=>$dict_key));<br />
return TRUE;<br />
}<br />
</pre><br />
<br />
Function Database::updateWhere throws an exception if query is bad, and you can catch it if you want and handle it as necessary, or you can just ignore it and application will display error message with a stacktrace and such.<br />
<br />
Exceptions registered so far:<br />
<br />
;RackTablesError<br />
:Fatal, final error, usually annotated.<br />
<br />
;RTDatabaseError<br />
:"Soft" database error (UNIQUE/FOREIGN KEY constraint violation or timeout).<br />
<br />
;RTGatewayError<br />
:An external gateway raised an error or the data it returned was corrupt or otherwise invalid.<br />
<br />
;EntityNotFoundException<br />
:Requested record could not be found in the database.<br />
<br />
;InvalidArgException<br />
:At least one of the arguments provided to a function had invalid value, and that value did NOT come from user's input. This means a programming error and cannot be worked around.<br />
<br />
;InvalidRequestArgException<br />
:Ditto, but the value was supplied by the user, and the error should be handled with an "inline" error message.<br />
<br />
;RTBuildLVSConfigError<br />
:LVS keepalived text compilation failed.<br />
----<br />
<br />
= RackCode =<br />
<pre><br />
# identifier<br />
ID ::= ^[[:alnum:]]([\. _~-]?[[:alnum:]])*$<br />
# identifier in brackets<br />
PREDICATE ::= [ID]<br />
DEFINE ::= define PREDICATE<br />
# identifier in curly braces<br />
TAG ::= {ID}<br />
# identifier in curly braces, starting with dollar sign<br />
AUTOTAG ::= {$ID}<br />
# context modifier<br />
CTXMOD ::= clear | insert TAG | remove TAG<br />
# context modifier list<br />
CTXMODLIST ::= CTXMODLIST CTXMOD | CTXMOD<br />
UNARY_EXPRESSION ::= true | false | TAG | AUTOTAG | PREDICATE | (EXPRESSION) | not UNARY_EXPRESSION<br />
# logical AND<br />
AND_EXPRESSION ::= AND_EXPRESSION and UNARY_EXPRESSION | UNARY_EXPRESSION<br />
# logical OR<br />
EXPRESSION ::= EXPRESSION or AND_EXPRESSION | AND_EXPRESSION<br />
GRANT ::= allow EXPRESSION | deny EXPRESSION<br />
DEFINITION ::= DEFINE EXPRESSION<br />
ADJUSTMENT ::= context CTXMODLIST on EXPRESSION<br />
# RackCode permission text<br />
CODETEXT ::= CODETEXT GRANT | CODETEXT DEFINITION | CODETEXT ADJUSTMENT | GRANT | DEFINITION | ADJUSTMENT<br />
</pre><br />
Comments in RackCode last from the first <tt>#</tt> character to the end of current line and are filtered out automatically:<br />
<pre><br />
allow {tech support} # or {admins} <--- note where comment starts<br />
and {assets} # <--- this is still a part of "allow" statement<br />
<br />
deny {guests}<br />
</pre><br />
<br />
= API =<br />
== Hello, World! ==<br />
To enable all RackTables functions and load all necessary system data, it is enough to include one file.<br />
<pre><br />
<?php<br />
<br />
include ('inc/init.php');<br />
// do something<br />
<br />
?><br />
</pre><br />
<br />
There is a special parameter, which tells, if current file is intended to be run by web-server or from a command line. In the latter case neither authentication nor authorization is performed.<br />
<pre><br />
<?php<br />
<br />
$script_mode = TRUE;<br />
include ('inc/init.php');<br />
<br />
echo "I am a crontab script!\n";<br />
// do something<br />
<br />
?><br />
</pre><br />
<br />
== Searching for the appropriate library function ==<br />
The easy way to determine which function does what you need to is analyze how the corresponding web interface request is processed.<br />
<br />
Each modification through web causes HTTP POST request being sent with at least these base parameters: 'page', 'tab', 'op'.<br />
There is the $ophandler array in wwwroot/inc/navigation.php filled with function names for each triplet of base web operation parameters.<br />
<br />
Then, when you determine the handler function name for you operation (like object creating), you could examine its code in wwwroot/inc/ophandlers.php. It usually calls appropriate functions from database.php.<br />
<br />
Also, there are some trivial operations which have no special ophandler function. Then the universal database wrapper called tableHandler takes place. It makes direct SQL queries, building them by $opspec_list array data.<br />
<br />
<br />
== Realms ==<br />
There are several principal realms in !RackTables database. Any realm contains zero, one or more records. Each such record is addressed by its ID (primary key).<br />
<br />
;object<br />
:All servers, switches, UPSes, wireless, cable management and any other stuff, which is viewed and managed on the main "Objects" page.<br />
;ipv4net<br />
:all IPv4 networks<br />
;ipv6net<br />
:all IPv6 networks<br />
;user<br />
:All local accounts. There is at least one local account in any RackTables system (admin). There may be more.<br />
;rack<br />
:All racks.<br />
;file<br />
:All files.<br />
;ipv4vs<br />
:All IPv4 virtual services.<br />
;ipv4rspool<br />
:All IPv4 real server pools.<br />
<br />
== function scanRealmByText ($realm, $ftext = "") ==<br />
;realm<br />
:String equal to one of the realms shown above.<br />
;ftext<br />
:Optional filter text. If this text is empty, all records of the realm are returned. If it is not empty, it is interpreted as a !RackCode expression. This expression is then evaluated against each record of the realm and only those records, for which the filter returned TRUE, are returned.<br />
<br />
<pre><br />
<?php<br />
<br />
include ('inc/init.php');<br />
<br />
$allusers = scanRealmByText ('user');<br />
$smallnetworks = scanRealmByText ('ipv4net', '{small network}');<br />
$unmounted_objects = scanRealmByText ('object', '{$unmounted}');<br />
<br />
?><br />
</pre><br />
<br />
== function spotEntity ($realm, $id) ==<br />
This is the right function to get information about some record, for which you know where it belongs to and what its key value is. If this information isn't available, it has to be discovered somehow first.<br />
<br />
;realm<br />
:Realm name.<br />
;id<br />
:Record number (key value, ID...).<br />
<br />
<pre><br />
<?php<br />
<br />
include ('inc/init.php');<br />
<br />
$adminuser = spotEntity ('user', 1); // Admin account is always number 1.<br />
$myspecialfile = spotEntity ('file', 12345);<br />
$serverinfo = spotEntity ('object', 67890);<br />
<br />
?><br />
</pre><br />
<br />
== function amplifyCell (&$record, $dummy = NULL) ==<br />
It is assumed, that spotEntity() loads only basic data about the record requested. "Basic" means enough for renderCell() to do its job or to render a row in a table. To get detailed information about the "cell" it is necessary to execute amplifyCell() on it:<br />
<pre><br />
<?php<br />
include ('inc/init.php');<br />
<br />
$adminuser = spotEntity ('user', 1); // Admin account is always number 1.<br />
amplifyCell ($adminuser);<br />
<br />
$unmounted_objects = scanRealmByText ('object', '{$unmounted}');<br />
array_walk ($unmounted_objects, 'amplifyCell');<br />
?><br />
</pre><br />
<br />
== function renderCell ($cell) ==<br />
Render cell structure as a rectangular block with icon, name, tags and other information. Available since 0.17.2.<br />
<br />
= Dictionary =<br />
== Where the data is ==<br />
Since release 0.17.2 all records are stored in file <tt>inc/dictionary.php</tt>:<br />
<pre><br />
$dictionary = array<br />
(<br />
1 => array ('chapter_id' => 1, 'dict_value' => 'BlackBox'),<br />
2 => array ('chapter_id' => 1, 'dict_value' => 'PDU'),<br />
3 => array ('chapter_id' => 1, 'dict_value' => 'Shelf'),<br />
4 => array ('chapter_id' => 1, 'dict_value' => 'Server'),<br />
5 => array ('chapter_id' => 1, 'dict_value' => 'DiskArray'),<br />
6 => array ('chapter_id' => 1, 'dict_value' => 'TapeLibrary'),<br />
7 => array ('chapter_id' => 1, 'dict_value' => 'Router'),<br />
8 => array ('chapter_id' => 1, 'dict_value' => 'Network switch'),<br />
9 => array ('chapter_id' => 1, 'dict_value' => 'PatchPanel'),<br />
10 => array ('chapter_id' => 1, 'dict_value' => 'CableOrganizer'),<br />
11 => array ('chapter_id' => 1, 'dict_value' => 'spacer'),<br />
12 => array ('chapter_id' => 1, 'dict_value' => 'UPS'),<br />
[...]<br />
</pre><br />
<br />
== meaning of chapter ID ==<br />
<pre><br />
mysql> SELECT * FROM Chapter;<br />
+----+--------+-----------------------------+<br />
| id | sticky | name |<br />
+----+--------+-----------------------------+<br />
| 1 | yes | RackObjectType | <br />
| 2 | yes | PortType | <br />
| 11 | no | server models | <br />
| 12 | no | network switch models | <br />
| 13 | no | server OS type | <br />
| 14 | no | switch OS type | <br />
| 16 | no | router OS type | <br />
| 17 | no | router models | <br />
| 18 | no | disk array models | <br />
| 19 | no | tape library models | <br />
| 21 | no | KVM switch models | <br />
| 22 | no | multiplexer models | <br />
| 23 | no | console models | <br />
| 24 | no | network security models | <br />
| 25 | no | wireless models | <br />
| 26 | no | fibre channel switch models | <br />
| 27 | no | PDU models | <br />
+----+--------+-----------------------------+<br />
17 rows in set (0.00 sec)<br />
</pre><br />
<br />
== wikilinks ==<br />
It is possible to render a record as an URL:<br />
<pre>[[ something | http://somewhere/ ]]</pre><br />
However, it is up to the editor, if to include URL into description or not. URLs can be added, changed and removed from particular records later, if it makes sense.<br />
<br />
== G-markers ==<br />
Text before the marker is always used for OPTGROUP in SELECT element. The difference is in the way the text is rendered as a plain text or a clickable URL. GSKIP makes OPTGROUP name to be skipped. GPASS passes OPTGROUP name on the text:<br />
<pre><br />
719 => array ('chapter_id' => 24, 'dict_value' => '[[Cisco%GPASS%ASR 1006 | http://cisco.com/en/US/products/ps9438/index.html]]'),<br />
720 => array ('chapter_id' => 13, 'dict_value' => '[[BSD%GSKIP%OpenBSD 3.3 | http://openbsd.org/33.html]]'),<br />
</pre><br />
<br />
[[Image:dictionary-G-markers.png]]<br />
<br />
= Customizing =<br />
== Overriding the search procedure ==<br />
<br />
RackTables contains API allowing to customize search. Two ways of customizing <br />
are available:<br />
<br />
a) You could change text request (search terms) before passing it to standard search procedure;<br />
<br />
b) You could either modify the search results list returned by the standard search procedure, or fill that list completely by yourself.<br />
<br />
Of course, you can combine the methods above.<br />
<br />
First, you need Racktables to include your code. Racktables tries to include <br />
the user's php lib called "wwwroot/inc/local.php". To be honest, the actual<br />
include path is "$path_to_local_php", which by default equals to <br />
"$racktables_confdir . '/local.php'". $racktables_confdir, consequently, by default<br />
is the dir where the library files are stored (wwwroot/inc). You could override<br />
either of these paths by making separate entry point (custom index.php), or in <br />
secret.php. If you want to actively use plugin model, you may want to write a<br />
generic local.php scanning your custom plugins directory and including files from<br />
it. This technique will allow you install plugins by simply putting them into this dir,<br />
and to easily exchange plugins with the community.<br />
<br />
So, you've decided to store your local.php in the default location and override<br />
the search procedure. Lets take an example. We want to take a URL in search box,<br />
extract hostname from it, resolve it into an IP address and than display the search<br />
results for this address. Proper local.php is below:<br />
<pre><br />
<?php<br />
//step 1<br />
$page['search']['handler'] = 'searchHandler_Local';<br />
<br />
function searchHandler_Local ()<br />
{<br />
// step 2<br />
$terms = trim ($_REQUEST['q']);<br />
<br />
// step 3<br />
if (preg_match("/^(http:\/\/)/", $terms))<br />
{ // Search by IP if URL was given<br />
preg_match("/^(http:\/\/)?([^\/]+)/i", $terms, $matches);<br />
$terms = gethostbyname($matches[2]);<br />
}<br />
<br />
// step 4 <br />
$results = searchEntitiesByText ($terms);<br />
<br />
// step 5<br />
// modify the $results you need to<br />
<br />
// step 6<br />
renderSearchResults ($terms, $results);<br />
}<br />
<br />
?><br />
</pre><br />
<br />
Let's describe this simple script step-by step.<br />
<br />
Step 1. First we overwrite the search handler procedure name, replacing the standard one<br />
by the custom 'searchHandler_Local'. Please note that you can not chain overrides - <br />
as soon you set procedure name in $page['search']['handler'] (as well as any other <br />
handler) the old handler is forgotten, and the new one is responsible for calling it,<br />
if it decides to.<br />
<br />
Step 2. We need to retrieve the search request. It is passed in 'q' HTTP GET parameter to<br />
the search handler.<br />
<br />
Step 3. We rewrite the search request text replacing URL to the corresponding IP address.<br />
It is an example of using the way (a) of customizing RackTables search (see above)<br />
<br />
Step 4. Let the standard search procedure do its job. We call searchEntitiesByText for that.<br />
<br />
Step 5. Here you could change the results returned by standard function. This array structure<br />
is pretty complex, you may want to examine it by calling var_dump. The array is indexed by<br />
search method (like 'object' or 'ipv6addressbydescr'). The rest structure depends of the first<br />
key value. If you want to display your very own search results section, you could add the unknown<br />
key into this array which will be used as a header for this results section. The HTML code for its<br />
body will be the value of $results by the given key.<br />
<br />
Step 6. Display the search results using renderSearchResults standard function.<br />
<br />
== Adding a custom report ==<br />
There is a simple way to write custom reports and embed them into the RackTables user interface.<br />
<br />
All you need to do is write a report rendering function, apparently using such RackTables API functions<br />
like scanRealmByText, spotEntity and renderCell, and register this function as a report rendering handler.<br />
This example should make it clear:<br />
<br />
1. Save the code below into the plugins/test-report.php file:<br />
<pre><br />
<?php<br />
<br />
$tabhandler['reports']['test'] = 'renderTestReport'; // register a report rendering function<br />
$tab['reports']['test'] = 'Test Report'; // title of the report tab<br />
<br />
function renderTestReport()<br />
{<br />
// fill the HW type stat array<br />
$stat = array();<br />
$total = 0;<br />
$filter = '{switch} and {Moscow}';<br />
foreach (scanRealmByText ('object', $filter) as $switch)<br />
{<br />
$attributes = getAttrValues ($switch['id']);<br />
if (isset ($attributes[2]))<br />
{<br />
$attr = $attributes[2];<br />
if (! isset ($stat[$attr['key']]))<br />
$stat[$attr['key']] = array<br />
(<br />
'value' => $attr['a_value'],<br />
'count' => 0,<br />
);<br />
++$stat[$attr['key']]['count'];<br />
++$total;<br />
}<br />
}<br />
<br />
// display the stat array<br />
echo "<h2>Moscow switches HW types report ($total)</h2><ul>";<br />
foreach ($stat as $type_id => $type)<br />
{<br />
$type_filter = $filter . ' and {$attr_2_' . $type_id . '}';<br />
$link = '<a href="' . makeHref (array ('page' => 'depot', 'cfe' => $type_filter)) . '">' . $type['count'] . ' devices</a>';<br />
echo "<li>${type['value']} - $link</li>";<br />
}<br />
echo '</ul>';<br />
}<br />
<br />
?><br />
</pre><br />
<br />
2. To install your report into RackTables, place the file in the plugins directory.<br />
<br />
This report displays switch devices located in Moscow, grouped by their hardware model types. Each line of output contains the device count of corresponding model and a link to view the device list, like this:<br />
<pre><br />
Moscow switches HW types report (2)<br />
* Cisco Catalyst 2960G-24PC - <a>1 devices</a><br />
* Cisco Catalyst 2960G-24TC - <a>1 devices</a><br />
</pre><br />
<br />
= 802.1Q internals =<br />
== execution of "pull-only" and "pull+push" sync requests ==<br />
[[Image:RackTables-8021Q-sync.png]]<br />
<br />
<br />
= SNMP sync =<br />
== Overview ==<br />
The feature evolved as a procedure intended to be run once for any given device. The main procedure is built around the ifTable SNMP tree, which belongs to IF-MIB (very old and ubiquitous one). With regard to network switches, everything is done in the doSwitchSNMPmining() function, located in inc/snmp.php.<br />
<br />
The function uses FQDN (hostname or IP/IPv6) if set, then try IP numbers to use as target host, fail in any other cases.<br />
<br />
First, subsets of ifTable are taken and combined in a way to produce a PHP array of all interfaces (with MAC address info for each interface).<br />
<br />
Then, for each item in the interface list, a "processor" is tried from the list of processors (which is known for each supported product number, that is, SNMP OID). This way, there is a list of "processor" items and a list of known switches, where each item uses one or more processors to process the list of interfaces. There is also a vendor-specific procedure for things like serial number or console port type.<br />
<br />
Each processor item is built as follows:<br />
* 'pattern' stands for PCRE pattern, which is tried against interface name (ifDescr in SNMP).<br />
* 'replacement' is a PCRE replacement for it (most often interface names need to be compressed into something of reasonable length, e.g. 'GigabitEthernet1/2/3' -> 'gi1/2/3').<br />
* 'label' stands for port's visible label ('replacement' was for port's interface name, i.e. the one which switch's operating system uses) in SQL it is Port.label.<br />
* 'dict_key' stands for a special value which can be defined in one of two forms: either "N2" or "N1-N2" (in the former case N1 is taken to be equal to 1).<br />
<br />
N1 stands for IIF ID, its valid values are stored in the PortInnerInterface table.<br />
N2 stands for OIF ID, its values are stored in Dictionary chapter 2.<br />
<br />
For example, the most popular interface, "hardwired 1000Base-T" may be written as either 24 or '1-24'.<br />
For an "empty XENPAK" port, use '5-1079'.<br />
IIF stands for "Inner InterFace" and OIF stands for "Outer InterFace"<br />
In the Port table, IIF ID is stored in the "iif_id" column and OIF ID in the "type" column.<br />
this way the description of "dict_key" in a processor item<br />
<br />
The 'known_switches' array is used to map processors and other information to specific switch models.<br />
* 'dict_key' is the dictionary ID which represents the switch model. The list of known models is defined in dictionary.php.<br />
* 'text' is a basic description of the device that is presented to the user after discovery is complete.<br />
* 'processors' lists which processors are applied to the device.<br />
* 'ifDescrOID' is an optional attribute used in cases where the SNMP ifDescr data does not include unique values (e.g. all interfaces are named 'Ethernet Interface'). It specifies the name of the table which does indeed contain unique interface names.<br />
* 'try_next_proc' controls the way different processors are applied. It only refers to if the PCRE pattern has matched or not. In the case of TRUE, the port is created as prescribed and processing of the current interface goes on with the next processor item. In the case of FALSE, the port is added and no more processor items are tried for the current interface (procedure goes on to the next interface).<br />
<br />
When it comes to adding support for another switch, the best route is to study the device to find out which physical ports it has and how they are represented in SNMP. In particular, 'try_next_proc' is used for combo ports (ones allowing either copper or SFP media under the same OS interface). The work is much easier when some other device from the same product line already exists in snmp.php. Some product lines only have different OIDs and dict_key values, while everything else is the same (e.g. a switch which has PoE ports and one which does not).<br />
<br />
=== Environmental requirements ===<br />
This function uses symbolic OIDs to access the devices which in turn requires base MIBs to be installed and configured properly. If they're not you'll get ''"Fatal SNMP error"'' on the webpage and ''"PHP Warning: snmp2_get(): Invalid object identifier: sysObjectID.0 in /var/www/rt/inc/snmp.php"'' in the webserver error log.<br />
<br />
In case of ''Debian GNU/Linux'' (squeeze and up), for example, this means that apart from <tt>php5-snmp</tt> there must be <tt>snmp-mibs-downloader</tt> installed, the MIBs downloaded and <tt>/etc/snmp/snmp.conf</tt> edited to allow their use. Do not forget to restart php (apache) after the changes.<br />
<br />
== Example 1: Arista 7124S ==<br />
This is a switch which has 24 SFP+ ports, two management ports and one power supply.<br />
<br />
SNMP returns the following names for the ifDescr table:<br />
* Ethernet1<br />
* Ethernet2<br />
* ...<br />
* Ethernet24<br />
* Management1<br />
* Management2<br />
<br />
Add to dictionary.php:<br />
<pre><br />
1610 => array ('chapter_id' => 12, 'dict_value' => 'Arista%GPASS%7124S'),<br />
</pre><br />
<br />
Add to snmp.php:<br />
<pre><br />
$iftable_processors['arista-any-SFP+'] = array<br />
(<br />
'pattern' => '@^Ethernet([[:digit:]]+)$@',<br />
'replacement' => '\\1',<br />
'dict_key' => '9-1084',<br />
'label' => '\\1',<br />
'try_next_proc' => FALSE,<br />
);<br />
<br />
$iftable_processors['arista-management'] = array<br />
(<br />
'pattern' => '@^Management(1|2)$@',<br />
'replacement' => 'mgmt\\1',<br />
'dict_key' => '1-24',<br />
'label' => 'Management',<br />
'try_next_proc' => FALSE,<br />
);<br />
</pre><br />
<br />
<pre><br />
'30065.1.3011.7124.3282' => array<br />
(<br />
'dict_key' => 1610,<br />
'text' => 'DCS-7124S: 24 SFP+/10000',<br />
'processors' => array ('arista-any-SFP+', 'arista-management'),<br />
),<br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=503FeatureWishlist2013-05-16T16:22:12Z<p>Adoom42: /* Feature Wishlist */</p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys (EntityLink, for example)<br />
* Manage plugins from the web interface<br />
** Install/uninstall, enable/disable capability capability<br />
** Install/uninstall features handle DB table creation/destruction</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=501FeatureWishlist2013-05-15T15:23:05Z<p>Adoom42: </p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.<br />
* Provide an 'Integrity Check' report which lists problems<br />
** Tables using the MyISAM engine which should be using InnoDB<br />
** Missing system-level rows (Attributes, for example)<br />
** Missing foreign keys or triggers<br />
** Invalid data which cannot be constrained using foreign keys (EntityLink, for example)</div>Adoom42https://wiki.racktables.org/index.php?title=FAQ&diff=481FAQ2013-03-04T17:54:34Z<p>Adoom42: /* Ask the developers to write a patch for you. */</p>
<hr />
<div>= RackTables FAQ =<br />
<br />
== How do I edit this wiki? ==<br />
Send a message to devteam@racktables.org.<br />
<br />
== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==<br />
RackTables only supports some specific switch models, and yours is not one of them. <br />
<br />
There are two ways to add support for new switch models. Both involve [http://bugs.racktables.org/bug_report_page.php filing a Mantis ticket].<br />
=== Write a patch yourself. ===<br />
* Review [[RackTablesDevelGuide#SNMP_sync|SNMP sync]] for background information.<br />
* Attach the patch to the Mantis ticket.<br />
=== Ask the developers to write a patch for you. ===<br />
The following information is necessary.<br />
* The exact model/part number of the device.<br />
* For a device which features SFP (GBIC, X2 etc) pluggable ports, specify which of these pluggable ports are "combo" (IOW, alternate socket for a copper port under the same name) and which are standalone ports.<br />
If possible, add the following information:<br />
* Manufacturer's markup of device's ports (this can be "21, 22, 23, 24", "21X, 22X, 23X, 24X" or even "21, 22, 23C, 23F, 24C, 24F")<br />
* Dump of SNMP info:<br />
<pre><br />
snmpwalk -v 1 -c public switchname sysDescr.0<br />
snmpwalk -v 1 -c public switchname sysObjectID.0<br />
snmpwalk -v 1 -c public switchname ifTable<br />
</pre><br />
If the device is modular or stackable, also walk ENTITY-MIB:<br />
<pre><br />
snmpwalk -v 1 -c public switchname .1.3.6.1.2.1.47<br />
</pre><br />
<br />
== Rack thumb images are broken ==<br />
There are two common reasons for this:<br />
# A mis-formatted local.php extension file. For images to work correctly, every PHP file of your RackTables, which begins with '''<?php''' tag, CAN NOT have a newline before the tag. Every PHP file of your RackTables, which ends with '''?>''' tag, CAN NOT have a newline after the tag.<br />
# GD library is not working (although it probably was at the time of installation). This can be confirmed by means of phpinfo() and fixed with the help of package manager of your server and RackTables README file.<br />
<br />
== How do I browse objects by object type? ==<br />
FILL ME IN<br />
<br />
== How do I handle blade systems/modular switches? ==<br />
You can have one object represent the chassis, and other objects represent the blades. See the documentation on [[RackTablesUserGuide#Containers|Containers]] for details.<br />
<br />
== How do I re-order racks in a row? ==<br />
In versions prior to 0.20, RackTables sorts in alphabetical order. A work-around is to prefix each rack's name with a number:<br />
* "01 F14"<br />
* "02 E14"<br />
* "03 D14"<br />
* "04 C14"<br />
* "05 B14"<br />
* "06 A14"<br />
<br />
Starting with 0.20, you can manually sort racks. View the row, then click the "Manage racks" tab.<br />
<br />
== How do I log out (and log in after that?) ==<br />
To log out: Use the "Click here to logout" link. When presented with the username/password prompt, do not enter anything. Instead, press "Cancel".<br />
<br />
To log in: Press your browser's "back" button to return to any of the normal pages (without "index.php?logout" in the URL) and enter your username/password.<br />
<br />
== How do I enable IPv4 for object type X? ==<br />
Answered by Ray Robertson:<br />
<pre><br />
Configuration --> User Interface --> Change<br />
<br />
Edit the entry for 'List source: IPv4-enabled objects'<br />
<br />
e.g.<br />
List source: IPv4-enabled objects {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798}<br />
<br />
To determine an object's typeid, hover your mouse pointer over the 'Object type' field when viewing the object. The typeid will be revealed in the URL.<br />
</pre><br />
<br />
<br />
'''Scenario:''' <br />
<br />
At Company X you have a proprietary transceiver-type device that is network accessible & can be assigned an IP. You add a new RackObjectType called "Transceiver". To add the IPv4 tab to new "Transceiver" objects, do the following.<br />
<br />
<pre><br />
1. Navigate to Main > Configuration > Dictionary > RackObjectType.<br />
<br />
2. Mouse-over the new RackObjectType you created, in this case "Transceiver". In this example, the Transceiver typeid is 50012.<br />
<br />
3. Now navigate to Main > Configuration > User Interface > Change.<br />
<br />
4. Scroll down to the item/entry "List source: IPv4-enabled objects". <br />
<br />
5. Now go to the end of the line, and enter "or {$typeid_50012}". <br />
<br />
6. Your new line looks like: {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798} or {$typeid_50012}<br />
<br />
7. Save changes.<br />
<br />
8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.<br />
</pre><br />
==How do I decode the IPv4 addresses stored in RackTables MySQL database?==<br />
RackTables stores all IPv4 addresses in their natural representation (32-bit unsigned integers like 180879936). The most reliable way is to use RackTables PHP function spotEntity(), which will return a structure filled with assorted fields, including a dotted-quad representation of IP address. If for whatever reason you decide to fetch the data directly from MySQL database, the simplest way of converting the intergers to dotted-quad (10.200.2.64) form and back is to use MySQL's functions INET_NTOA() and INET_ATON() respectively:<br />
<pre><br />
mysql> SELECT ip, INET_NTOA(ip), mask FROM IPv4Network;<br />
+-----------+---------------+------+<br />
| ip | INET_NTOA(ip) | mask |<br />
+-----------+---------------+------+<br />
| 180879360 | 10.200.0.0 | 31 |<br />
| 180879362 | 10.200.0.2 | 31 |<br />
| 180879364 | 10.200.0.4 | 31 |<br />
| 180879366 | 10.200.0.6 | 31 |<br />
| 180879616 | 10.200.1.0 | 26 |<br />
| 180879680 | 10.200.1.64 | 26 |<br />
| 180879872 | 10.200.2.0 | 26 |<br />
| 180879936 | 10.200.2.64 | 26 |<br />
| 180880192 | 10.200.3.64 | 26 |<br />
| 180880384 | 10.200.4.0 | 26 |<br />
| 180880448 | 10.200.4.64 | 26 |<br />
+-----------+---------------+------+<br />
11 rows in set (0.00 sec)<br />
</pre><br />
==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==<br />
This is a known issue. The workaround is to upgrade from 0.17.x to 0.18.7, then to 0.19.x. Release 0.18.7 can be downloaded directly from the git repository: https://github.com/RackTables/racktables/zipball/RackTables-0.18.7<br />
<br />
==How do I manage tags on a series of objects (networks etc) automaticaly?==<br />
<pre><br />
<?php<br />
<br />
$script_mode = TRUE;<br />
include '/usr/local/racktables/wwwroot/inc/init.php';<br />
<br />
# add tag "right" to each object tagged "left"<br />
$added = getTagByName ('right');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
rebuildTagChainForEntity ('object', $object['id'], array ($added));<br />
<br />
# remove tag "left" from each object tagged "right"<br />
$removed = getTagByName ('left');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
deleteTagForEntity ('object', $object['id'], $removed['id']);<br />
<br />
?><br />
</pre><br />
<br />
= RackTables contributions =<br />
== How can I visualise network topology? ==<br />
See [[Visualisation with GraphViz]] for ideas using GraphViz.</div>Adoom42https://wiki.racktables.org/index.php?title=FAQ&diff=370FAQ2012-08-31T20:56:21Z<p>Adoom42: /* How do I re-order racks in a row? */</p>
<hr />
<div>= RackTables FAQ =<br />
<br />
== How do I edit this wiki? ==<br />
# Get a SourceForge account.<br />
# <del>Open the wiki</del> (you are already here).<br />
# Make sure you are still logged in (now wiki has copied your account from SF).<br />
# Send a message with your SF account name to devteam@racktables.org requesting acces.<br />
When you receive a response, your account will be in the "editors" group.<br />
<br />
== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==<br />
RackTables only supports some specific switch models, and yours is not one of them. <br />
<br />
There are two ways to add support for new switch models. Both involve [http://bugs.racktables.org/bug_report_page.php filing a Mantis ticket].<br />
=== Write a patch yourself. ===<br />
* Review [[RackTablesDevelGuide#SNMP_sync|SNMP sync]] for background information.<br />
* Attach the patch to the Mantis ticket.<br />
=== Ask the developers to write a patch for you. ===<br />
* The following information is necessary.<br />
** The exact model/part number of the device.<br />
** For a device which features SFP (GBIC, X2 etc) pluggable ports, specify which of these pluggable ports are "combo" (IOW, alternate socket for a copper port under the same name) and which are standalone ports.<br />
* If possible, add the following information:<br />
** Manufacturer's markup of device's ports (this can be "21, 22, 23, 24", "21X, 22X, 23X, 24X" or even "21, 22, 23C, 23F, 24C, 24F")<br />
** Dump of SNMP info:<br />
<pre><br />
snmpwalk -v 1 -c public switchname sysDescr.0<br />
snmpwalk -v 1 -c public switchname sysObjectID.0<br />
snmpwalk -v 1 -c public switchname ifTable<br />
</pre><br />
<br />
== Rack thumb images are broken ==<br />
There are two common reasons for this:<br />
# A mis-formatted local.php extension file. For images to work correctly, every PHP file of your RackTables, which begins with '''<?php''' tag, CAN NOT have a newline before the tag. Every PHP file of your RackTables, which ends with '''?>''' tag, CAN NOT have a newline after the tag.<br />
# GD library is not working (although it probably was at the time of installation). This can be confirmed by means of phpinfo() and fixed with the help of package manager of your server and RackTables README file.<br />
<br />
== How do I browse objects by object type? ==<br />
FILL ME IN<br />
<br />
== How do I handle blade systems/modular switches? ==<br />
You can have one object represent the chassis, and other objects represent the blades. See the documentation on [[RackTablesUserGuide#Containers|Containers]] for details.<br />
<br />
== How do I re-order racks in a row? ==<br />
In versions prior to 0.20, RackTables sorts in alphabetical order. A work-around is to prefix each rack's name with a number:<br />
* "01 F14"<br />
* "02 E14"<br />
* "03 D14"<br />
* "04 C14"<br />
* "05 B14"<br />
* "06 A14"<br />
<br />
Starting with 0.20, you can manually sort racks. View the row, then click the "Manage racks" tab.<br />
<br />
== How do I log out (and log in after that?) ==<br />
To log out: Use the "Click here to logout" link. When presented with the username/password prompt, do not enter anything. Instead, press "Cancel".<br />
<br />
To log in: Press your browser's "back" button to return to any of the normal pages (without "index.php?logout" in the URL) and enter your username/password.<br />
<br />
== How do I enable IPv4 for object type X? ==<br />
Answered by Ray Robertson:<br />
<pre><br />
Configuration --> User Interface --> Change<br />
<br />
Edit the entry for 'List source: IPv4-enabled objects'<br />
<br />
e.g.<br />
List source: IPv4-enabled objects {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798}<br />
<br />
To determine an object's typeid, hover your mouse pointer over the 'Object type' field when viewing the object. The typeid will be revealed in the URL.<br />
</pre><br />
<br />
<br />
'''Scenario:''' <br />
<br />
At Company X you have a proprietary transceiver-type device that is network accessible & can be assigned an IP. You add a new RackObjectType called "Transceiver". To add the IPv4 tab to new "Transceiver" objects, do the following.<br />
<br />
<pre><br />
1. Navigate to Main > Configuration > Dictionary > RackObjectType.<br />
<br />
2. Mouse-over the new RackObjectType you created, in this case "Transceiver". In this example, the Transceiver typeid is 50012.<br />
<br />
3. Now navigate to Main > Configuration > User Interface > Change.<br />
<br />
4. Scroll down to the item/entry "List source: IPv4-enabled objects". <br />
<br />
5. Now go to the end of the line, and enter "or {$typeid_50012}". <br />
<br />
6. Your new line looks like: {$typeid_2} or {$typeid_4} or {$typeid_7} or {$typeid_8} or {$typeid_12} or {$typeid_445} or {$typeid_447} or {$typeid_798} or {$typeid_50012}<br />
<br />
7. Save changes.<br />
<br />
8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.<br />
</pre><br />
==How do I decode the IPv4 addresses stored in RackTables MySQL database?==<br />
RackTables stores all IPv4 addresses in their natural representation (32-bit unsigned integers like 180879936). The most reliable way is to use RackTables PHP function spotEntity(), which will return a structure filled with assorted fields, including a dotted-quad representation of IP address. If for whatever reason you decide to fetch the data directly from MySQL database, the simplest way of converting the intergers to dotted-quad (10.200.2.64) form and back is to use MySQL's functions INET_NTOA() and INET_ATON() respectively:<br />
<pre><br />
mysql> SELECT ip, INET_NTOA(ip), mask FROM IPv4Network;<br />
+-----------+---------------+------+<br />
| ip | INET_NTOA(ip) | mask |<br />
+-----------+---------------+------+<br />
| 180879360 | 10.200.0.0 | 31 |<br />
| 180879362 | 10.200.0.2 | 31 |<br />
| 180879364 | 10.200.0.4 | 31 |<br />
| 180879366 | 10.200.0.6 | 31 |<br />
| 180879616 | 10.200.1.0 | 26 |<br />
| 180879680 | 10.200.1.64 | 26 |<br />
| 180879872 | 10.200.2.0 | 26 |<br />
| 180879936 | 10.200.2.64 | 26 |<br />
| 180880192 | 10.200.3.64 | 26 |<br />
| 180880384 | 10.200.4.0 | 26 |<br />
| 180880448 | 10.200.4.64 | 26 |<br />
+-----------+---------------+------+<br />
11 rows in set (0.00 sec)<br />
</pre><br />
==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==<br />
This is a known issue. The workaround is to upgrade from 0.17.x to 0.18.7, then to 0.19.x. Release 0.18.7 can be downloaded directly from the git repository: https://github.com/RackTables/racktables/zipball/RackTables-0.18.7<br />
<br />
==How do I manage tags on a series of objects (networks etc) automaticaly?==<br />
<pre><br />
<?php<br />
<br />
include '/usr/local/racktables/wwwroot/inc/init.php';<br />
<br />
# add tag "right" to each object tagged "left"<br />
$added = getTagByName ('right');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
rebuildTagChainForEntity ('object', $object['id'], array ($added));<br />
<br />
# remove tag "left" from each object tagged "right"<br />
$removed = getTagByName ('left');<br />
foreach (scanRealmByText ('object', '{left}') as $object)<br />
deleteTagForEntity ('object', $object['id'], $removed['id']);<br />
<br />
?><br />
</pre></div>Adoom42https://wiki.racktables.org/index.php?title=Roadmap&diff=364Roadmap2012-08-25T17:56:57Z<p>Adoom42: Created page with "= 0.21 = * Modular devices * Cable tracing * Duplicate IPv4 networks * Properly escape all strings containing content from the database * Replace HTTP authentication with a lo..."</p>
<hr />
<div>= 0.21 =<br />
* Modular devices<br />
* Cable tracing<br />
* Duplicate IPv4 networks<br />
* Properly escape all strings containing content from the database<br />
* Replace HTTP authentication with a login page</div>Adoom42https://wiki.racktables.org/index.php?title=Main_Page&diff=363Main Page2012-08-25T17:53:17Z<p>Adoom42: </p>
<hr />
<div>[[File:RackTables-development-roadmap-2011Q3.png|391px|thumb|right]]<br />
* for RackTables users<br />
** [[RackTablesInstallHowto | Installation HOWTO]]<br />
** [[RackTablesAdminGuide | Administrator's guide]]<br />
** [[RackTablesUserGuide | User's guide]]<br />
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)<br />
** [[FAQ]]<br />
** [[LDAP | LDAP configuration]]<br />
* for RackTables hackers<br />
** [[SourceCode | Working with RackTables source code]]<br />
** [[RackTablesDevelGuide | Developer's guide]]<br />
** [[FeatureWishlist | Feature wishlist]]<br />
* for development team<br />
** [[NewRelease | Checklist and procedures to make a new release]]<br />
** [[ProjectInfrastructure | Project infrastructure]]<br />
** [[Roadmap]]</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=362FeatureWishlist2012-08-21T16:08:43Z<p>Adoom42: </p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.<br />
* Allow duplicate IPv4 networks, at least for the private space.<br />
** When assigning a non-unique IP to an object, ask the user to specify which subnet it is from.</div>Adoom42https://wiki.racktables.org/index.php?title=RackTablesUserGuide&diff=361RackTablesUserGuide2012-08-19T17:28:23Z<p>Adoom42: /* Port and links */</p>
<hr />
<div>= Port and links =<br />
A port or physical interface is part of an object which you can connect a cable to. Each port can have a local name, that is how this port is visible from the OS point of view. For a Linux system that will be eth0, eth1, etc. Visible label is what is physically written on the port.<br />
<br />
Depending on the manufacturer you may observe labels as "1", "2", etc. or something else. Port type is an essential property that allows port connections to be properly arranged. It lets you know that you won't be able to connect optical and copper ports together with one cable. Some ports have an L2 address. It's helpful to populate those, as you may find it handy to find ports by L2 addresses while investigating your STP tree.<br />
<br />
Reserving a port is simply adding a comment to it, thus preventing it to be linked. A good reservation can be "Reserved for a field engineer laptop". Linking ports is creating a connection between them. That is plugging a cable to them. Only ports with compatible types can be linked. Say, RJ-45/100-Base TX can be linked to RJ-45/1000-Base TX, but can't be linked to LC/100-BASE FX. In many cases you'll need to add a bunch of ports from a switch. In this case there is a text area and a format selector. Just choose your device and format, paste the output to the textarea and click "Parse output" button. Also, you need to choose which port type is to be used, since it's not possible to guess that from the output.<br />
----<br />
<br />
= Networking =<br />
== IP subnets ==<br />
This tab manages IPv4 resources. All IPv4 addresses are grouped to subnets. Subnets make a hierarchy, which is computed and displayed automatically. An IPv4 address __can__ belong to a network. Sometimes it doesn't. There is an option ("Enable IPv4 address allocations w/o covering network") to deal with that. When it is enabled, the system refuses to assign "martian" IP addresses to objects. However, this option doesn't affect already assigned "martian" addresses.<br />
<br />
== IP addresses ==<br />
Every IP address can be either bound to an interface or free. On the other hand, it can<br />
be either reserved or not. That makes 4 possible states: bound - reserved, bound - unreserved, free - reserved<br />
free - unreserved. The first state is considered as "conflicting" and will be shown red-highlited.<br />
An IP address may have a "Name" assigned to it, which is intended to be used as a short comment.<br />
An example would be "The default GW" or "Reserved for field engineer"<br />
Binding an address to an interface is called "allocation". The interface is a rack object plus an interface name.<br />
The interface name can be the same as a physical port label on that box or something else.<br />
If you are binding it to a linux box with 2 physical ports, you might want to name interfaces as<br />
eth0, eth1, eth0:4, eth1.110, etc, whereas your physical port names will be eth1 and eth2<br />
The difference between ports and interfaces is that say a switch may have 24 ports and only 1 interface,<br />
which is accessable from any of those ports. Generally, one IP address can be bound only to one interface,<br />
otherwise it's considered as a "collision". However, there are exceptions and a tool to mark<br />
those exceptions. There is a "bond type" or "interface type", which can be either "Regular"<br />
or "Shared" or "Virtual". Shared means that 2 or more peers share the same IP address<br />
like it's done in VRRP or HSRP. Usually, there is only one box possessing it at a time<br />
but when it dies, another one will have it. Shared bonds will not conflict with each other,<br />
but will conflict with regular bindings of the same IP address. Virtual interface is<br />
an assignment that usually don't broadcast itself through the network, but will allow<br />
the OS to accept packets with that IP address sent to the box. This is widely used<br />
in loadbalancing technics where loadbalancers simply do ARP proxy; they rewrite L2 address<br />
in L2 frames with target's address and resend them back to the network. Virtual interfaces<br />
do not conflict with any other interface types. Note: do not use virtual interfaces if<br />
your loadbalancer uses NAT. There is a NAT tab for that instead.<br />
<br />
== NATv4 ==<br />
Boxes can translate their own L4 addresses to other L4 addresses on other boxes. This is called<br />
NAT. In protocol selection box you can choose 2 protocols so far, UDP and TCP. Source is one of<br />
IP addresses assigned to the box and after a colon is a box for numerical port. As a target you<br />
have to choose a target IP address and port it will be translated to. Add a decription if you like.<br />
After submitting the form you will find that if there was an object assined to the target IP address<br />
it will be shown as well. A single source IP address/port can be assigned to multiple target IP<br />
addresses/ports. That will represent an L4 loadbalancing. And vice versa, multiple sources can be<br />
translated to one target.<br />
----<br />
<br />
= Rackspace =<br />
<br />
== Rack design tab ==<br />
Rack design defines the physical layout of a rack cabinet. Most common reason to use the tab is absence of back rails, although any other design can be defined. In this tab you can change mounting atoms' state between 'free' and 'absent'. A selected checkbox means atom presence.<br />
<br />
== Rack problems tab ==<br />
Rack problems prevent free rackspace from being used for mounting. Such rackspace is considered unusable. After the problem is gone, the atom can become free again. In this tab you can change atoms' state from free to unusable and back. A selected checkbox means a problem.<br />
----<br />
<br />
= Live PTR =<br />
First of all, an important notice has to be done about names (or "descriptions") of IP addresses. If you know about the real objects, to which addresses belong, it is recommended to create those objects and then allocate IP addresses to them. This approach will keep your dataset consistent and cross-linked. Address descriptions normally should contain supplementary, but useful information: the role or a well-known DNS name of a particular address.<br />
<br />
The feature allows matching description of each IP address of the current IP subnet with DNS PTR record, resolved online. !RackTables highlights each address accordingly to its current description and DNS data; however, it is a rough estimation if each particular description is correct or not. It is left up to the user to decide, if DNS data, as more accurate, should be imported into DB.<br />
----<br />
<br />
= Containers =<br />
Container objects were introduced in version 0.19 to support various scenarios.<br />
<br />
Similar to the port compatibility matrix, the object compatibility matrix defines valid relationships. It's located on the Configuration page.<br />
<br />
You choose an object's container using the 'Select container' link on the object's Properties tab. This link is only visible if the object type exists as a child in the object compatibility matrix.<br />
<br />
Objects may have multiple containers. This is to support unique scenarios such as a blade server which is used to host virtual machines. It could potentially have two valid containers - the blade server chassis as well as the VM cluster.<br />
<br />
If an object contains any other objects, they are listed on the Object->View page.<br />
<br />
== Physical Objects ==<br />
New object types include Network chassis and Server chassis.<br />
<br />
Common container scenarios:<br />
* Blade server chassis -> blade (server or network switch blades)<br />
* Network chassis -> blade<br />
* Shelf -> modems (or any other small objects sitting on the shelf)<br />
<br />
When mousing over the container object's name in the rackspace area, the hover displays a list of all contained objects. Only immediate children are listed, grand-children, great-grand-children, etc. are not.<br />
<br />
== Virtual Objects ==<br />
New object types include VM, VM Cluster, VM Resource Pool and VM Virtual Switch. Although the terminology is common to VMware environments, the object types may be used in a generic manner to support other scenarios.<br />
<br />
The VIRTUAL_OBJ_LISTSRC Config option specifies which object types are virtual. Virtual objects may not be mounted in a rack. They also lack the asset tag, barcode and label fields.<br />
<br />
A Virtual Resources link on the front page leads to a summary page detailing clusters, resource pools, hypervisors and virtual switches.<br />
<br />
The Hypervisor attribute was added and associated with Server objects. It may be set to Yes or No. When selecting a container for a VM or VM Virtual Switch, the only servers listed are those with the Hypervisor attribute set to Yes. This was done to limit the number of entries displayed in the selector pop-up window.<br />
<br />
The NATv4, RS pools, keepalived.conf and Live ports tabs are not associated with VMs. If you'd like them to be, edit the appropriate Config entries to include {$typeid_1504} which is the objtype_id of VMs.<br />
<br />
=== Example Scenarios===<br />
The object type is in parentheses.<br />
<br />
Example 1: Individual server hosting VMs<br />
<br />
* MyHypervisor (Server)<br />
** MyAppServer (VM)<br />
** MyWebServer (VM)<br />
** MyDatabaseServer (VM)<br />
<br />
Example 2: Cluster of servers hosting VMs (VMware)<br />
<br />
* MyCluster (VM Cluster)<br />
** MyHypervisor1 (Server)<br />
** MyHypervisor2 (Server)<br />
** MyHypervisor3 (Server)<br />
*** SpecialServer1 (VM)<br />
** MyDistributedSwitch (VM Virtual Switch)<br />
** DevPool (VM Resource Pool)<br />
*** DevAppServer1 (VM)<br />
*** DevAppServer2 (VM)<br />
** ProductionPool (VM Resource Pool) <br />
*** ProdAppServer1 (VM)<br />
*** ProdAppServer2 (VM)<br />
<br />
Example 3: Cluster of servers hosting VMs (XenServer)<br />
<br />
* DevPool (VM Resource Pool)<br />
** MyHypervisor1 (Server)<br />
** MyHypervisor2 (Server)<br />
** DevAppServer1 (VM)<br />
** DevAppServer2 (VM)<br />
* ProductionPool (VM Resource Pool) <br />
** MyHypervisor3 (Server)<br />
** MyHypervisor4 (Server)<br />
** ProdAppServer1 (VM)<br />
** ProdAppServer2 (VM)<br />
----<br />
<br />
= RackCode =<br />
== Tags ==<br />
The language operates on "tags", which are plain text strings, most commonly single words much like blog post tags. A tag usually indicates a fact of belonging to certain class or group, or it may express, that certain boolean predicate is true. In !RackTables, for example, several objects can be tagged with "development" and this will show their functional assignment. Some of those objects could be tagged with "room 112" to reflect their location. Tags may have parent tags. The "room 112" tag (and perhaps some others) could have "main building" as its parent, altogether corresponding to building plan.<br />
<br />
Tags serve dual purpose: to classify entities for easier browsing or asset management and to form security context. Autotags are added into the context automatically and have dollar sign prepended to their ID. Lettercase in tag names sometimes matters: one can't create two tags, whose names only differ in case, but tag names referenced in the !RackCode are searched in the security context with case preserved. IOW, if some entity is tagged with "Dogs", a {dogs} tag test will never return true.<br />
<br />
== Tag chain ==<br />
A tag chain is just an unordered set of tags with an important extension: if a tag is present on the chain, all its parent tags, up to the topmost one, are always present too. This is true for each tag on the chain.<br />
<br />
== Predicates ==<br />
A predicate is a boolean non-recursive function, which returns either true or false. The function is referenced by its symbolic name and may use both tags and other predicates to build boolean expressions. The order of definitions matters, i.e. the predicate must be declared at the moment of a grant rule evaluation, if the rule is referencing it (this is verified automatically). A predicate can only be defined once (it cannot be redefined later).<br />
<br />
== Automatic tags ==<br />
Autotags aren't shown by default, this may be changed on the "user interface" config page. Below is the list of currently used autotags (as for 0.20.0).<br />
<br />
=== Navigation tags ===<br />
;$page_something<br />
: Always set; "something" is the name of the current page.<br />
;$tab_something<br />
: Always set; "something" is the name of the current tab.<br />
; $op_something<br />
: Only set when an operation (change request) "something" is being processed, usually immediately after hitting some kind of "submit" control. Everything happens behind the scenes, then the user is redirected to some view (often, but not always the same he arrived from) and a message log is displayed on the top of the page.<br />
;$any_op<br />
: Set, if any operation is being processes. Having this autotag in a deny rule '''should''' (not finished yet) block all modifications to the database.<br />
<br />
=== Common tags ===<br />
;$lgcn_somename<br />
: LDAP group CN. Groups are taken from user's memberOf LDAP attribute during authentication.<br />
;$untagged<br />
: Set for any entity (but except users), which __can__ have tags, but __doesn't__ have any tags set.<br />
<br />
=== Location tags ===<br />
;$any_location<br />
: set, when current focus is a location container<br />
;$locationid_000<br />
: set to the ID of the current location container<br />
<br />
=== Row tags ===<br />
;$any_row<br />
: set, when current focus is a rack row<br />
;$rowid_000<br />
: set to the ID of the current rack row<br />
<br />
=== Rack tags ===<br />
;$any_rack<br />
: set, when current focus is a rack<br />
;$rackid_000<br />
: set to the ID of the current rack<br />
<br />
=== User tags ===<br />
;$userid_000<br />
: Numerical user ID of the current user account, if the account exists in the local database.<br />
;$username_somename<br />
: Username of the current user.<br />
<br />
=== Object tags ===<br />
;$any_object<br />
: Always present in all views for objects (isn't it equivalent to $page_object?).<br />
;$id_000<br />
: When operating on a rack object (asset), this tag is always set with 000 being its database ID.<br />
;$typeid_000<br />
: Same as above, but for the ID of the type of the operated object. E. g., servers produce $typeid_4.<br />
;$cn_somename<br />
: '''If''' an object has such a common name "somename", which makes the above string be a valid tag name, this autotag is added to the context.<br />
;$attr_X_Y<br />
: Set, if object has a defined dictionary attribute. X is an attribute id and Y is a dictionary key of the value. For example, if the object has two assigned attributes: HW type(2) = Cisco Catalyst 6509-E(148), and SW type(4) = Cisco IOS 12.2(252), than two autotags are attached to this object: $attr_2_148 and $attr_4_252<br />
;$no_asset_tag<br />
: set if current object has no asset number<br />
;$unmounted<br />
: Set for objects, which have no IP addresses allocated.<br />
;$nameless<br />
: Set for objects, which __don't__ have a name, although they __should__ have one according to config ("List source: object, for which common name should be set").<br />
;$portless<br />
: Set for objects, which have zero ports.<br />
;$runs_8021Q<br />
: Set for any object, which has 802.1Q order (that is, a VLAN domain and a switch template) assigned (introduced in 0.18.0)<br />
;$8021Q_domain_000<br />
: Set for any object, which has 802.1Q order. Contains numeric ID of 802.1Q domain of the order<br />
;$8021Q_tpl_000<br />
: Set for any object, which has 802.1Q order. Contains numeric ID of 802.1Q template of the order<br />
<br />
=== IP network tags ===<br />
;$any_net<br />
: set for any IP network<br />
;$any_ip4net<br />
: set for any IPv4 network<br />
;$any_ip6net<br />
: set for any IPv6 network<br />
;$ip4netid_000<br />
: set for IPv4 networks. Contains numeric network ID<br />
;$ip6netid_000<br />
: set for IPv6 networks. Contains numeric network ID<br />
;$masklen_eq_NNN<br />
: set for any IP network. Contains network prefix length in bits<br />
;$runs_8021Q<br />
: set for IP networks which have VLANs attached to it<br />
;$vlan_NNN<br />
: set for IP networks which have VLANs attached to it. Contains numeric VLAN ID (tag number).<br />
;$spare_NNN<br />
: set for IP networks which have unallocated space in them. Contains the numeric prefix length of unallocated range. If network has multiple unallocated ranges of different sizes, multiple such tags will be assigned to it.<br />
;$aggregate<br />
: set for IP networks which have subnetworks<br />
;$ip4net-192-168-0-0-24<br />
: set for any IPv4 network. Contains network IP and prefix length separated by dashes.<br />
<br />
=== File tags ===<br />
;$any_file<br />
: Set, when current focus is a file.<br />
;$fileid_000<br />
: Holds file ID, if the current focus is a file.<br />
<br />
=== 802.1Q template tags ===<br />
;$any_vst<br />
: set for any 802.1Q template<br />
;$vstid_000<br />
: set for any 802.1Q template. Contains numeric ID of template<br />
<br />
=== Virtual service tags ===<br />
;$any_vs<br />
: set for any virtual service<br />
;$any_ipv4vs<br />
: set for any IPv4 virtual service<br />
;$any_ipv6vs<br />
: set for any IPv6 virtual service<br />
;$ipvsid_000<br />
: set to ID of virtual service<br />
;$unused<br />
: set for such virtual services which do not have any RS Pool-Load Balancer links<br />
<br />
=== Real server pool tags ===<br />
;$any_rsp<br />
: set for all RS pools (which is the same as $any_ipv4rsp)<br />
;$any_ipv4rsp<br />
: set for all RS pools (RS pools can contain both IPv4 and IPv6 addresses)<br />
;$ipv4rspid_000<br />
: set to RS pool ID<br />
;$unused<br />
: set for such RS poold which do not have any Virtual Service-Load Balancer links<br />
<br />
=== Operation-specific tags ===<br />
;$fromvlan_NNNN<br />
: Set, when a port is being removed from VLAN with the given VLAN ID (by means of LiveVLANs or 802.1Q ports feature).<br />
;$tovlan_NNNN<br />
: Likewise, when a port is being added to a VLAN.<br />
;$vlan_NNNN<br />
: Likewise, when a port is being either added OR removed, equivalent to "{$fromvlan_NNNN} or {$tovlan_NNNN}" RackCode expression.</div>Adoom42https://wiki.racktables.org/index.php?title=FeatureWishlist&diff=358FeatureWishlist2012-08-03T03:42:31Z<p>Adoom42: Created page with "=== Feature Wishlist === This is a random list of desired features. * Clone an object ** Some attributes would be copied (SW version, RAM) but some would not (serial number, ..."</p>
<hr />
<div>=== Feature Wishlist ===<br />
This is a random list of desired features.<br />
<br />
* Clone an object<br />
** Some attributes would be copied (SW version, RAM) but some would not (serial number, MAC addresses)<br />
* Re-discover an object<br />
** NICs may be exchanged in a server, or a blade may be added to a switch. Re-discovering the object would add/change ports and other attributes, but wouldn't delete any existing data unless confirmed by the user.<br />
* Trace the cable path<br />
** There are cases where a device is connected to a patch panel, which is then connected to another patch panel. This chain could continue for several hops until reaching the final destination device. Display the 'final destination' port and object on the port listing. Also provide a 'traceroute' link which displays all path details in a pop-up window.</div>Adoom42https://wiki.racktables.org/index.php?title=Main_Page&diff=357Main Page2012-07-31T03:38:03Z<p>Adoom42: </p>
<hr />
<div>[[File:RackTables-development-roadmap-2011Q3.png|391px|thumb|right]]<br />
* for RackTables users<br />
** [[RackTablesInstallHowto | Installation HOWTO]]<br />
** [[RackTablesAdminGuide | Administrator's guide]]<br />
** [[RackTablesUserGuide | User's guide]]<br />
** [[8021Q | 802.1Q VLAN management in RackTables]] (still work in progress)<br />
** [[FAQ]]<br />
** [[LDAP | LDAP configuration]]<br />
* for RackTables hackers<br />
** [[SourceCode | Working with RackTables source code]]<br />
** [[RackTablesDevelGuide | Developer's guide]]<br />
** [[FeatureWishlist | Feature wishlist]]<br />
* for development team<br />
** [[NewRelease | Checklist and procedures to make a new release]]<br />
** [[ProjectInfrastructure | Project infrastructure]]</div>Adoom42https://wiki.racktables.org/index.php?title=ProjectInfrastructure&diff=356ProjectInfrastructure2012-07-31T03:23:34Z<p>Adoom42: /* racktables.org mail */</p>
<hr />
<div>==Mapping of assets==<br />
=== DNS ===<br />
racktables.org domain is currently registered through GoDaddy, which also provides 2 free nameservers. Aaron manages the domain.<br />
<br />
=== racktables.org mail ===<br />
racktables.org mail is handled by zohomail.com. Zoho Mail offers free service for up to three e-mail addresses. Two mailing lists exist, "devteam" and "info", which are setup to forward all messages to every development team member.<br />
<br />
=== racktables-users mail ===<br />
FreeLists is a great free service without accompanying advertisements. The only drawback about it is that it is non-profit and can go down some day.<br />
=== Bug tracker, wiki, demo host ===<br />
Arnaud Launay is the administrator of a server, which currently runs this wiki, Mantis and the RackTables demo. To get SSH access there, be a team member and find someone who already has access.<br />
=== Statistics ===<br />
SF download stats work for the downloads. Google analytics works for the content of racktables.org and demo.racktables.org.<br />
=== Everything else ===<br />
SourceForge. SVN, racktables.org HTTP vhost, downloads and shell service.<br />
----<br />
==Backup procedure==<br />
===racktables-users===<br />
Send an empty email with subject "who racktables-users" to ecartis@freelists.org and you will get a list of all subscribers. Save it to the backup directory as "racktables-users.txt".<br />
===SourceForge data===<br />
# Project page, "Project admin", "Features", "XML export": save the file into backup directory as "racktables_export.xml".<br />
# Backup stuff accessible from SF SSH only:<br />
<pre>ssh -t YOUR_SF_USERNAME,racktables@shell.sourceforge.net create<br />
adminrepo --checkout svn<br />
svnadmin dump /svnroot/racktables | gzip > racktables-svn-dump.bin.gz<br />
adminrepo --discard svn<br />
tar czf racktables.org.tar.gz /home/project-web/racktables/htdocs/<br />
<br />
sf-help | fgrep 'ssh -p'<br />
# Note the hostname and the port and copy the files from SF shell to your directory:<br />
scp -P 24006 YOUR_SF_USERNAME@shell4.sourceforge.net:~/racktables-svn-dump.bin.gz .<br />
scp -P 24006 YOUR_SF_USERNAME@shell4.sourceforge.net:~/racktables.org.tar.gz .<br />
<br />
# in SF shell again<br />
rm racktables-svn-dump.bin.gz racktables.org.tar.gz<br />
shutdown<br />
</pre><br />
Now the backup directory must have these files:<br />
* racktables-svn-dump.bin.gz<br />
* racktables-users.txt<br />
* racktables.org.tar.gz<br />
* racktables_export.xml<br />
Wrap this stuff into a single archive file with a meaningful name and '''save it to a safe place''':<br />
<pre><br />
tar cf RackTables-project-backup-`date +%Y%m%d`.tar ./racktables*<br />
</pre><br />
<br />
<br />
===Bug tracker, wiki data===<br />
SSH into the host and create a new backup directory.<br />
mkdir ~/RackTables-apps-backup<br />
cd ~/RackTables-apps-backup<br />
<br />
Copy the applications into the backup directory. This is important because they contain uploaded files and configuration settings.<br />
cp -r ~/www/bugs .<br />
cp -r ~/www/wiki .<br />
<br />
Export the database for each application.<br />
mysqldump -u <username> -p <dbname> > bugs.sql<br />
mysqldump -u <username> -p <dbname> > wiki.sql<br />
<br />
Wrap it all up in a single archive file and '''save it to a safe place''':<br />
cd ~/<br />
tar czf RackTables-apps-backup-`date +%Y%m%d`.tar.gz ./RackTables-apps-backup</div>Adoom42