Difference between revisions of "FAQ"

From RackTables Wiki
Jump to navigation Jump to search
m (→‎Write a patch yourself.: also mention GitHub PRs)
 
(11 intermediate revisions by 4 users not shown)
Line 2: Line 2:
  
 
== How do I edit this wiki? ==
 
== How do I edit this wiki? ==
# Get a SourceForge account.
+
Send a message to devteam@racktables.org.
# <del>Open the wiki</del> (you are already here).
 
# Make sure you are still logged in (now wiki has copied your account from SF).
 
# Send a message with your SF account name to devteam@racktables.org requesting acces.
 
When you receive a response, your account will be in the "editors" group.
 
  
 
== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==
 
== Why does the SNMP sync feature return Unknown OID (n.n.n.n.n) ==
 
RackTables only supports some specific switch models, and yours is not one of them.  
 
RackTables only supports some specific switch models, and yours is not one of them.  
  
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].
+
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].
 
=== Write a patch yourself. ===
 
=== Write a patch yourself. ===
* Review [[RackTablesDevelGuide#SNMP_sync|SNMP sync]] for background information.
+
# Review [[RackTablesDevelGuide#SNMP_sync|this text]] for background information.
* Attach the patch to the Mantis ticket.
+
# Add necessary changes to your copy of RackTables source code and test them.
 +
# Propose the changes as a GitHub pull request or attach the patch to a new ticket in MantisBT.
 +
 
 
=== Ask the developers to write a patch for you. ===
 
=== Ask the developers to write a patch for you. ===
* The following information is necessary.
+
The following information is necessary.
** The exact model/part number of the device.
+
* The exact model/part number of the device.
** 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.
+
* 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.
* If possible, add the following information:
+
If possible, add the following information:
** 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")
+
* 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")
** Dump of SNMP info:
+
* Dump of SNMP info:
 
<pre>
 
<pre>
 
snmpwalk -v 1 -c public switchname sysDescr.0
 
snmpwalk -v 1 -c public switchname sysDescr.0
snmpwalk -v 1 -c public switchname sysObjectID.0
+
snmpwalk -On -v 1 -c public switchname sysObjectID.0
 
snmpwalk -v 1 -c public switchname ifTable
 
snmpwalk -v 1 -c public switchname ifTable
 
</pre>
 
</pre>
 +
If the device is modular or stackable, also walk ENTITY-MIB:
 +
<pre>
 +
snmpwalk -v 1 -c public switchname .1.3.6.1.2.1.47
 +
</pre>
 +
If the device is a Cisco stackable switch and its sysObjectID ends with .9.1.516, then enter the configuration command
 +
<pre>
 +
no snmp-server sysobjectid type stack-oid
 +
</pre>
 +
, reboot switch and re-collect the sysObjectID.0
 +
 +
Attach the information to the Mantis ticket.  Do not post it inline, as it consumes too much screen real estate.
  
 
== Rack thumb images are broken ==
 
== Rack thumb images are broken ==
Line 34: Line 43:
  
 
== How do I browse objects by object type? ==
 
== How do I browse objects by object type? ==
FILL ME IN
+
On the "Objects" page under the "Tag filters" section there should be a text area where you can enter:
 +
<pre>
 +
{$typeid_XXX}
 +
</pre>
 +
Replace XXX with the Type ID of the type you are looking for. The easiest way to do that is to open object's page of an object that has the type you need and then to click the link next to the "Object type" header in the Summary block:<br>
 +
[[File:Object_type.png]]
  
 
== How do I handle blade systems/modular switches? ==
 
== How do I handle blade systems/modular switches? ==
Line 55: Line 69:
 
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.
 
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.
  
== How do I enable IPv4 for object type X? ==
+
== How do I enable IPv4 for object type X in versions before 0.20.6? ==
 
Answered by Ray Robertson:
 
Answered by Ray Robertson:
<pre>
+
<code>
 
Configuration --> User Interface --> Change
 
Configuration --> User Interface --> Change
 
   
 
   
Line 66: Line 80:
 
   
 
   
 
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.
 
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.
</pre>
+
</code>
  
  
Line 73: Line 87:
 
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.
 
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.
  
<pre>
+
<code>
 
1. Navigate to Main > Configuration > Dictionary > RackObjectType.
 
1. Navigate to Main > Configuration > Dictionary > RackObjectType.
  
Line 89: Line 103:
  
 
8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.
 
8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.
</pre>
+
</code>
 +
 
 
==How do I decode the IPv4 addresses stored in RackTables MySQL database?==
 
==How do I decode the IPv4 addresses stored in RackTables MySQL database?==
 
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:
 
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:
Line 111: Line 126:
 
11 rows in set (0.00 sec)
 
11 rows in set (0.00 sec)
 
</pre>
 
</pre>
 +
 +
==Is there a simpler way to export IP addresses?==
 +
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}:
 +
 +
<pre>
 +
<?php
 +
$script_mode = TRUE;
 +
require 'wwwroot/inc/init.php';
 +
foreach (scanRealmByText ('object', '{debian wheezy}') as $object)
 +
{
 +
amplifyCell ($object);
 +
foreach ($object['ipv4'] + $object['ipv6'] as $ip_bin => $alloc)
 +
echo implode ("\t", [ $object['name'], $alloc['osif'], ip_format ($ip_bin) ]) . "\n";
 +
}
 +
</pre>
 +
 
==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==
 
==There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x==
 
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
 
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
Line 118: Line 149:
 
<?php
 
<?php
  
 +
$script_mode = TRUE;
 
include '/usr/local/racktables/wwwroot/inc/init.php';
 
include '/usr/local/racktables/wwwroot/inc/init.php';
  
Line 132: Line 164:
 
?>
 
?>
 
</pre>
 
</pre>
 +
 +
= RackTables contributions =
 +
== How can I visualise network topology? ==
 +
See [[Visualisation with GraphViz]] for ideas using GraphViz.

Latest revision as of 14:09, 27 October 2017

RackTables FAQ

How do I edit this wiki?

Send a message to devteam@racktables.org.

Why does the SNMP sync feature return Unknown OID (n.n.n.n.n)

RackTables only supports some specific switch models, and yours is not one of them.

There are two ways to add support for new switch models. Both involve filing a Mantis ticket.

Write a patch yourself.

  1. Review this text for background information.
  2. Add necessary changes to your copy of RackTables source code and test them.
  3. Propose the changes as a GitHub pull request or attach the patch to a new ticket in MantisBT.

Ask the developers to write a patch for you.

The following information is necessary.

  • The exact model/part number of the device.
  • 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.

If possible, add the following information:

  • 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")
  • Dump of SNMP info:
snmpwalk -v 1 -c public switchname sysDescr.0
snmpwalk -On -v 1 -c public switchname sysObjectID.0
snmpwalk -v 1 -c public switchname ifTable

If the device is modular or stackable, also walk ENTITY-MIB:

snmpwalk -v 1 -c public switchname .1.3.6.1.2.1.47

If the device is a Cisco stackable switch and its sysObjectID ends with .9.1.516, then enter the configuration command

no snmp-server sysobjectid type stack-oid

, reboot switch and re-collect the sysObjectID.0

Attach the information to the Mantis ticket. Do not post it inline, as it consumes too much screen real estate.

Rack thumb images are broken

There are two common reasons for this:

  1. 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.
  2. 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.

How do I browse objects by object type?

On the "Objects" page under the "Tag filters" section there should be a text area where you can enter:

{$typeid_XXX}

Replace XXX with the Type ID of the type you are looking for. The easiest way to do that is to open object's page of an object that has the type you need and then to click the link next to the "Object type" header in the Summary block:
Object type.png

How do I handle blade systems/modular switches?

You can have one object represent the chassis, and other objects represent the blades. See the documentation on Containers for details.

How do I re-order racks in a row?

In versions prior to 0.20, RackTables sorts in alphabetical order. A work-around is to prefix each rack's name with a number:

  • "01 F14"
  • "02 E14"
  • "03 D14"
  • "04 C14"
  • "05 B14"
  • "06 A14"

Starting with 0.20, you can manually sort racks. View the row, then click the "Manage racks" tab.

How do I log out (and log in after that?)

To log out: Use the "Click here to logout" link. When presented with the username/password prompt, do not enter anything. Instead, press "Cancel".

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.

How do I enable IPv4 for object type X in versions before 0.20.6?

Answered by Ray Robertson: Configuration --> User Interface --> Change

Edit the entry for 'List source: IPv4-enabled objects'

e.g. 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}

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.


Scenario:

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.

1. Navigate to Main > Configuration > Dictionary > RackObjectType.

2. Mouse-over the new RackObjectType you created, in this case "Transceiver". In this example, the Transceiver typeid is 50012.

3. Now navigate to Main > Configuration > User Interface > Change.

4. Scroll down to the item/entry "List source: IPv4-enabled objects".

5. Now go to the end of the line, and enter "or {$typeid_50012}".

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}

7. Save changes.

8. Navigate to one of your Transceiver objects, and confirm that the IPv4 tab is now present.

How do I decode the IPv4 addresses stored in RackTables MySQL database?

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:

mysql> SELECT ip, INET_NTOA(ip), mask FROM IPv4Network;
+-----------+---------------+------+
| ip        | INET_NTOA(ip) | mask |
+-----------+---------------+------+
| 180879360 | 10.200.0.0    |   31 |
| 180879362 | 10.200.0.2    |   31 |
| 180879364 | 10.200.0.4    |   31 |
| 180879366 | 10.200.0.6    |   31 |
| 180879616 | 10.200.1.0    |   26 |
| 180879680 | 10.200.1.64   |   26 |
| 180879872 | 10.200.2.0    |   26 |
| 180879936 | 10.200.2.64   |   26 |
| 180880192 | 10.200.3.64   |   26 |
| 180880384 | 10.200.4.0    |   26 |
| 180880448 | 10.200.4.64   |   26 |
+-----------+---------------+------+
11 rows in set (0.00 sec)

Is there a simpler way to export IP addresses?

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}:

<?php
$script_mode = TRUE;
require 'wwwroot/inc/init.php';
foreach (scanRealmByText ('object', '{debian wheezy}') as $object)
{
	amplifyCell ($object);
	foreach ($object['ipv4'] + $object['ipv6'] as $ip_bin => $alloc)
		echo implode ("\t", [ $object['name'], $alloc['osif'], ip_format ($ip_bin) ]) . "\n";
}

There is an "Unknown column 'is_userdefined'" PDO exception on upgrade from version 0.17.x to 0.19.x

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

How do I manage tags on a series of objects (networks etc) automaticaly?

<?php

$script_mode = TRUE;
include '/usr/local/racktables/wwwroot/inc/init.php';

# add tag "right" to each object tagged "left"
$added = getTagByName ('right');
foreach (scanRealmByText ('object', '{left}') as $object)
        rebuildTagChainForEntity ('object', $object['id'], array ($added));

# remove tag "left" from each object tagged "right"
$removed = getTagByName ('left');
foreach (scanRealmByText ('object', '{left}') as $object)
        deleteTagForEntity ('object', $object['id'], $removed['id']);

?>

RackTables contributions

How can I visualise network topology?

See Visualisation with GraphViz for ideas using GraphViz.