
Rackview Design
---------------

This tool was developed by the Open Source Development Lab to assist in
managing and visualizing the computer equipment in its data center.
OSDL provides a range of equipment for use by open source projects for
testing of Linux software, and periodically needs to add or reconfigure
the racks to meet new needs.  A tool to help manage and track this
information dynamically was needed, and was given priority to developing
it when OSDL moved into new facilities and a new data center needed to
be designed.

It is hoped that this tool will be directly useful to others wishing to
visualize their data center layouts.  But for those who wish or need to
customize it further, this document provides tips and explanations of
some of the tools internals and assumptions. 


Terminology
===========

host- An item that has its location determined relative to a position in
a rack or, if not rack mounted, its location in a building.

component- An item that has its location determined relative to a host

rack - a metal housing for hosts with vertically stacked mounting slots
spaced a standard distance (measured in "U"s) apart.

frame - a set of one or more racks placed side-by-side.  


Overview
========
Rackview is implemented as a Perl module named Eidetic::Racks.  This
encapsulates the logic required to collect and process the machine info
for the racks and to generate HTML for displaying those racks.  In
general you do this by creating a new Eidetic::Rack object and then
calling its toHtml() routine. 

The HTML produced by Eidetic::Racks includes no header, footer,
navigation, or any other such page structures.  It is expected that
these things are to be provided by higher level systems.  For instance,
a rackview.cgi script is included that adds in the HEAD, TITLE, BODY,
etc.  A commandline tool 'erackview' is also provided; this returns the
raw output from toHtml; it is expected that the user would use this tool
in conjuction with a templating system or else just 'cat' a header.inc
and footer.inc onto it, as desired.


Config File
===========
This section documents and explains the available fields in the
configuration file.

search_order - This parameter allows control over where rackview should
find its data.  Allowed values are 'dat' and/or 'db'.  It is possible to
list both, comma-separated; the first listed will be searched first, and
if no valid data is found (e.g., if the database is down), the next will
be used.

db_brand - The type of database to use.  Currently only 'mysql' is
supported. 

db_name - The name given to the database.  

db_host - The hostname or IP address of the machine serving the database

db_user - The database username that rackview should use to access the
data.  There is no reason to give more than read-only access to
rackview. 

db_pass - A password for controlling access to the database.  Leaving it
blank is permitted.  Note that if you specify a password, you may want
to tighten down access permissions to the config file.

dat_file - If data is to be loaded from a data file instead of the
database, specify the filename for that data with this parameter.

host_viewer - If specified, rackview will construct a URL based on the
value of this parameter for the host images.  The [%uid%] tag will be
replaced by the ID number of the host as appropriate.  One could use
this to hook into an hardware inventory database using CGI parameters,
for example, or could set up a series of static html files for the
hosts. 

rack_heat - Include display of heat information for rack.  1 to enable,
0 to disable.

frame_heat - Include display of heat information for entire frame.  1 to
enable, 0 to disable.

heat - Report all heat info.  1 to enable, 0 to disable.

warn - Include display of warnings about database issues.  1 to enable,
0 to disable.

alpha -  Report hosts in alphabetical order with U locations.  1 to
enable, 0 to disable.


Data Sources
============
Eidetic::Rack can load its data either from a database or a file.  The
latter is mainly provided as a means to get the tool up and running
quickly, for evaluation purposes; the principle intent of this tool is
to be used in conjunction with a database, so that the information can
be provided dynamically.  


Loading Rack Data from Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Eidetic::Racks utilizes Eidetic::Database to interact with mysql.  Look
at create_table_hosts.sql and create_table_host_types.sql in the sql/
directory to see the table schemas.  Several fields are required
in order for rackview to function; the remainder are optional and can be
modified or removed as desired.  The required fields are as follows:

 host_type table
   uid
   rsf
   descriptor
   Size_in_rack_u
   Max_btus
   Brand
   Brand_model_name
   Cooling_tons_max
  
 host table
   uid
   rsf
   descriptor           The hostname of the machine
   Rack_number          The ID number for the rack
   Host_type_uid        
   U_count_from_bottom
  
These two tables present a class/instance type of relationship.  Any two
hosts that share the same host_type are the same brand model number.  In
theory, the only differences would be the serial numbers and locational
positions.


Loading Rack Data from Data File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For data source flexibility, rackview allows loading its data from a
flatfile.  The file must contain a valid perl data structure, such as
generated by Data::Dumper.  This is loaded into rackview via a `do`
command. 

Note that for simplicity the class/instance distinction between host and
host_type is ignored when loading from a file.


Page Layout
===========
Each rack is drawn as a separate table, with positioning held together
using images, including an invisible 'blank.gif'.  All of the racks are
nested inside a parent table.

The individual host images are drawn using the GD::Image graphics
library.  This is done in the draw_host_png() routine of Eidetic::Racks.

Additional information about the hosts is displayed at the bottom of the
page. 

If you'd like to have a "U Ruler" displayed on the left & right of the
display, use the CGI parameter 'umarks=1' in the URL string.


Included Example
================
The principle motivation behind rackview was to assist the Open Source
Development Lab in better organizing its new lab layout and providing
its associates with an online interactive means of interacting with the
equipment.  Some of the 'interesting' parts of this work are provided
with rackview as an example, which you are free to reuse under the terms
of the GPL.

To provide a top level view of the racks and show how they're laid out
in our data center, a top-down image is used.  Any drawing application
able to emit images as GIF or PNG would be suitable; the example was
drawn using GNOME's open source 2D scalable vector graphics drawing
application, 'Sodipodi'.  This can be obtained from
http://sodipodi.sf.net.  The PNG was generated by taking a screenshot
using GIMP and cropping it to the appropriate size.

Integration of the PNG with rackview is done by representing the PNG as
an imagemap.  Different areas of the image are turned into 'hot spots'
that can be clicked on.  The URL for the anchor is constructed with the
appropriate parameters to cause rackview.cgi to display those racks.
For example:

<img src="top_view.png"
     usemap="#top_view_map" border="0">

<map name="top_view_map">
<area shape=rect coords="180,160,200,225"
       href="http://localhost/cgi-bin/rackview.cgi?rack_ids=00,001&umarks=1"
       onMouseOver="self.status='Frame 00, racks 000-001'; return true"
       onMouseOut="self.status=''; return true">
 ...
</map>

This causes a rectangular shaped area of the top_view.png specified by
the top left corner 180,160 and lower right corner 200,225 to become a
clickable region that leads to the URL indicated by the href.  The
onMouseOver and onMouseOut properties are Javascript snippets that get
executed when the user hovers the mouse cursor over the area.

