Difference between revisions of "RackTablesDevelGuide"
Infrastation (talk | contribs) |
Infrastation (talk | contribs) m (→rolling out: no Milestones) |
||
Line 114: | Line 114: | ||
[infrastation@shell-22005 ~]$ demoreload.sh 0.17.9 | [infrastation@shell-22005 ~]$ demoreload.sh 0.17.9 | ||
</pre> | </pre> | ||
− | |||
* In MantisBT mark version as released (Manage, Manage Projects, RackTables, Versions). | * In MantisBT mark version as released (Manage, Manage Projects, RackTables, Versions). | ||
* Log into SF shell service: | * Log into SF shell service: |
Revision as of 18:31, 27 May 2010
Contents
Strategic roadmap
Working with SVN repository
getting a working copy of maintenance line
# Anyone can read from the repository, but writing requires being a project developer. svn co https://racktables.svn.sourceforge.net/svnroot/racktables/branches/maintenance-0.17.x/ # Above command is for the maintenance line. For the trunk (see roadmap picture for exact # difference between two) respective command is: svn co https://racktables.svn.sourceforge.net/svnroot/racktables/trunk/
editing files
Use your favourite editor. Please consider existing code style: the default is to keep with Allman style (not with K&R, as was mistakenly stated here before). Indentation is always performed with tabs, please use any tab width you are comfortable with.
Here is an example of a function:
// take port list with order applied and return uplink ports in the same format function produceUplinkPorts ($domain_vlanlist, $portlist) { $ret = array(); $employed = array(); foreach ($domain_vlanlist as $vlan_id => $vlan) if ($vlan['vlan_type'] == 'compulsory') $employed[] = $vlan_id; foreach ($portlist as $port_name => $port) if ($port['vst_role'] != 'uplink') foreach ($port['allowed'] as $vlan_id) if (!in_array ($vlan_id, $employed)) $employed[] = $vlan_id; foreach ($portlist as $port_name => $port) if ($port['vst_role'] == 'uplink') { $employed_here = array(); foreach ($employed as $vlan_id) if (matchVLANFilter ($vlan_id, $port['wrt_vlans'])) $employed_here[] = $vlan_id; $ret[$port_name] = array ( 'vst_role' => 'uplink', 'mode' => 'trunk', 'allowed' => $employed_here, 'native' => 0, ); } return $ret; }
viewing exact changes
svn stat svn diff
submitting work
# if you have an account svn commit # and if you don't svn diff > my-cool-feature.patch # send the patch file by e-mail
Cutting a release
pre-release checklist
First make sure, that all necessary changes are already committed into the repository:
- Variable inc/config.php:$max_dict_key must be equal to the maximum value of key found at the end of inc/dictionary.php.
- Function database.php:getDictStats() must enumerate all chapter IDs, which are listed in install/init-dictbase.sql:Chapter (otherwise the stats are shown wrong).
- All release notes, if any, must appear both in upgrade script and in the README.
- Current date must be present on the version line of ChangeLog.
- Make sure, that upgrade.php has new version listed in $versionhistory and executeUpgradeBatch(). It is normal to accumulate updates in executeUpgradeBatch() long before the release, this way on the release day you will have nothing to do in upgrade.php. 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.
- Bump up CODE_VERSION in inc/config.php and DB_VERSION in install/init-dictbase.sql. DON'T do this unless you really intend to make a release right now.
- svn stat; svn commit
Then export from the trunk (or maintenance branch, whichever you are releasing from) and test the codebase.
- The source must be installable from the web. Click next-next-next and you're done. Dump the DB.
- Demo data must also be loadable and functional.
- The source must detect and upgrade the previous release correctly. Load the last release with its demo data, then upgrade it and dump the DB. Now compare to the previous dump, there must be no meaningful differences.
mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-upgraded.sql mysqldump --extended-insert=FALSE --order-by-primary racktables_db > ~/tmp/dump-fresh.sql diff -u ~/tmp/dump-fresh.sql ~/tmp/dump-upgraded.sql
- Now click a couple of links.
- Look into the error log of the server you used for the tests. There shouldn't be any messages produced by any test.
The above may happen repeated more, than once, until everything is fixed consistently.
the release itself
# from trunk (like early 0.16.x/0.18.x): svn cp \ https://racktables.svn.sourceforge.net/svnroot/racktables/trunk \ https://racktables.svn.sourceforge.net/svnroot/racktables/tags/RackTables-X.Y.Z # from maintenance (like 0.17.x): svn cp \ https://racktables.svn.sourceforge.net/svnroot/racktables/branches/maintenance-X.Y.x \ https://racktables.svn.sourceforge.net/svnroot/racktables/tags/RackTables-X.Y.z
rolling out
- Make a tarball:
svn export https://racktables.svn.sourceforge.net/svnroot/racktables/tags/RackTables-X.Y.z tar czf RackTables-X.Y.z.tar.gz RackTables-X.Y.z
- Upload the tarball onto SF project "files" area (FRS).
- Update the live demo page: create a new database, unpack tarball into new directory, reload database. Let old demo run for a couple of days more.
mysql> create database r293827_demo_X_Y_Z CHARACTER SET utf8 COLLATE utf8_general_ci; [infrastation@shell-22005 ~]$ demoreload.sh 0.17.9
- In MantisBT mark version as released (Manage, Manage Projects, RackTables, Versions).
- Log into SF shell service:
ssh -t YOUR_USERNAME,racktables@shell.sourceforge.net create
- Edit (vim) /home/groups/r/ra/racktables/htdocs/header.php to update $lastrelease. Make sure "download" and "demo" do work after that.
- Post a Freshmeat release announce here.
- Send a letter to the racktables-users list, if necessary.
Config options
Variables are stored in the Config SQL table:
mysql> describe Config; +-------------+-----------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+-----------------------+------+-----+---------+-------+ | varname | varchar(32) | NO | PRI | | | | varvalue | varchar(255) | NO | | | | | vartype | enum('string','uint') | NO | | string | | | emptyok | enum('yes','no') | NO | | no | | | is_hidden | enum('yes','no') | NO | | yes | | | description | text | YES | | NULL | | +-------------+-----------------------+------+-----+---------+-------+ 6 rows in set (0.00 sec)
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:
- upgrade.php
- install/init-dictbase.sql
- inc/ophandlers.php:resetUIConfig()
Default values must match regardless of the way they were set: initial setup, upgrade or UI reset.
Exceptions and error handling (in development)
Error handling now can be done by exceptions mechanism. index.php and process.php have been wrapped in
ob_start(); try{ ... ob_end_flush(); } catch { print_error_nicely(); }
kind of code, so every exception you miss and not catch will be printed instead of the page that had to be printed.
This saves a lot of code, take a look at a function
// before function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '') { if ($chapter_no <= 0) { showError ('Invalid args', __FUNCTION__); die; } global $dbxlink; $query = "update Dictionary set dict_value = '${dict_value}' where chapter_id=${chapter_no} " . "and dict_key=${dict_key} limit 1"; $result = $dbxlink->query ($query); if ($result == NULL) { showError ('SQL query failed', __FUNCTION__); die; } return TRUE; } // and after function commitUpdateDictionary ($chapter_no = 0, $dict_key = 0, $dict_value = '') { if ($chapter_no <= 0) throw InvalidArgException('$chapter_no', $chapter_no); Database::updateWhere(array('dict_value'=>$dict_value), 'Dictionary', array('chapter_id'=>$chapter_no, 'dict_key'=>$dict_key)); return TRUE; }
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 s stacktrace and such.
Exceptions registered so far:
class name | by | when |
---|---|---|
NotAuthorizedException | Authentication failed or user is not authorized to view current page | |
CodeCompilationError | RackCode compilcation failed | |
RealmNotFoundException | Realm not found | |
EntityNotFoundException | when an entity cannot be found in the database | |
NotUniqueException | when a record cannot be INSERTed into SQL table due to UNIQUE KEY constraint | |
InvalidArgException | lots of places | when at least one of the arguments provided to a function has invalid value |
InvalidRequestArgException | usually thrown by assert*Arg() functions | wrong argument in Request |
Exception | When it's not worth to create a special exception class |
RackCode
BNF/regexp | description |
---|---|
ID ::= ^[[:alnum:]]([\. _~-]?[[:alnum:]])*$ |
identifier |
PREDICATE ::= [ID] |
identifier in brackets |
DEFINE ::= define PREDICATE | |
TAG ::= {ID} |
identifier in curly braces |
AUTOTAG ::= {$ID} |
identifier in curly braces, starting with dollar sign |
CTXMOD ::= clear | insert TAG | remove TAG |
context modifier |
CTXMODLIST ::= CTXMODLIST CTXMOD | CTXMOD |
context modifier list |
UNARY_EXPRESSION ::= true | false | TAG | AUTOTAG | PREDICATE | (EXPRESSION) | not UNARY_EXPRESSION | |
AND_EXPRESSION ::= AND_EXPRESSION and UNARY_EXPRESSION | UNARY_EXPRESSION |
logical AND |
EXPRESSION ::= EXPRESSION or AND_EXPRESSION | AND_EXPRESSION |
logical OR |
GRANT ::= allow EXPRESSION | deny EXPRESSION | |
DEFINITION ::= DEFINE EXPRESSION | |
ADJUSTMENT ::= context CTXMODLIST on EXPRESSION | |
CODETEXT ::= CODETEXT GRANT | CODETEXT DEFINITION | CODETEXT ADJUSTMENT | GRANT | DEFINITION | ADJUSTMENT |
RackCode permission text |
Comments in RackCode last from the first # character to the end of current line and are filtered out automatically:
allow {tech support} # or {admins} <--- note where comment starts and {assets} # <--- this is still a part of "allow" statement deny {guests}
API
Hello, World!
To enable all RackTables functions and load all necessary system data, it is enough to include one file.
<?php include ('inc/init.php'); // do something ?>
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.
<?php $script_mode = TRUE; include ('inc/init.php'); echo "I am a crontab script!\n"; // do something ?>
Realms
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).
- object
- All servers, switches, UPSes, wireless, cable management and any other stuff, which is viewed and managed on the main "Objects" page.
- ipv4net
- All IPv4 networks.
- user
- All local accounts. There is at least one local account in any RackTables system (admin). There may be more.
- rack
- All racks.
- file
- All files.
- ipv4vs
- All IPv4 virtual services.
- ipv4rspool
- All IPv4 real server pools.
function scanRealmByText ($realm, $ftext = "")
- realm
- String equal to one of the realms shown above.
- ftext
- 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.
<?php include ('inc/init.php'); $allusers = scanRealmByText ('user'); $smallnetworks = scanRealmByText ('ipv4net', '{small network}'); $unmounted_objects = scanRealmByText ('object', '{$unmounted}'); ?>
function spotEntity ($realm, $id)
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.
- realm
- Realm name.
- id
- Record number (key value, ID...).
<?php include ('inc/init.php'); $adminuser = spotEntity ('user', 1); // Admin account is always number 1. $myspecialfile = spotEntity ('file', 12345); $serverinfo = spotEntity ('object', 67890); ?>
function amplifyCell (&$record, $dummy = NULL)
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:
<?php include ('inc/init.php'); $adminuser = spotEntity ('user', 1); // Admin account is always number 1. amplifyCell ($adminuser); $unmounted_objects = scanRealmByText ('object', '{$unmounted}'); array_walk ($unmounted_objects, 'amplifyCell'); ?>
function renderCell ($cell)
Render cell structure as a rectangular block with icon, name, tags and other information. Available since 0.17.2.
Dictionary
Where the data is
Since release 0.17.2 all records are stored in file inc/dictionary.php:
$dictionary = array ( 1 => array ('chapter_id' => 1, 'dict_value' => 'BlackBox'), 2 => array ('chapter_id' => 1, 'dict_value' => 'PDU'), 3 => array ('chapter_id' => 1, 'dict_value' => 'Shelf'), 4 => array ('chapter_id' => 1, 'dict_value' => 'Server'), 5 => array ('chapter_id' => 1, 'dict_value' => 'DiskArray'), 6 => array ('chapter_id' => 1, 'dict_value' => 'TapeLibrary'), 7 => array ('chapter_id' => 1, 'dict_value' => 'Router'), 8 => array ('chapter_id' => 1, 'dict_value' => 'Network switch'), 9 => array ('chapter_id' => 1, 'dict_value' => 'PatchPanel'), 10 => array ('chapter_id' => 1, 'dict_value' => 'CableOrganizer'), 11 => array ('chapter_id' => 1, 'dict_value' => 'spacer'), 12 => array ('chapter_id' => 1, 'dict_value' => 'UPS'), [...]
meaning of chapter ID
mysql> SELECT * FROM Chapter; +----+--------+-----------------------------+ | id | sticky | name | +----+--------+-----------------------------+ | 1 | yes | RackObjectType | | 2 | yes | PortType | | 11 | no | server models | | 12 | no | network switch models | | 13 | no | server OS type | | 14 | no | switch OS type | | 16 | no | router OS type | | 17 | no | router models | | 18 | no | disk array models | | 19 | no | tape library models | | 21 | no | KVM switch models | | 22 | no | multiplexer models | | 23 | no | console models | | 24 | no | network security models | | 25 | no | wireless models | | 26 | no | fibre channel switch models | | 27 | no | PDU models | +----+--------+-----------------------------+ 17 rows in set (0.00 sec)
wikilinks
It is possible to render a record as an URL:
[[ something | http://somewhere/ ]]
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.
G-markers
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:
719 => array ('chapter_id' => 24, 'dict_value' => '[[Cisco%GPASS%ASR 1006 | http://cisco.com/en/US/products/ps9438/index.html]]'), 720 => array ('chapter_id' => 13, 'dict_value' => '[[BSD%GSKIP%OpenBSD 3.3 | http://openbsd.org/33.html]]'),
Adding a custom report
(contributed by Craig Hoffman)
A slightly modified and simple version of a PHP script posted to the !RackTables mailing list (link). 98% of this code is not mine. It will generate a CSV file export.
In this example, I have a new attribute on some of my hosts called "IPv6"(attr_id 10000 for me). I wanted to be able to report on that, as well as its IPv4 counterpart. It also does a MySQL INET_NTOA conversion so that the IP address actually looks like something a human can read.
I place this file in the root of my webserver. If you place it elsewhere, and wish to call it from the "local.php" file included below, adjust the "/ipv6.php" location in local.php.
<?php $db=mysql_connect('localhost','root',''); if (!$db) { die('Not connected : ' . mysql_error()); } $db_selected = mysql_select_db('rt', $db); if (!$db_selected) { die ('Can\'t use foo : ' . mysql_error()); } //SQL query starts here $sql = "SELECT DISTINCT(RackObject.name) AS DeviceName, r2.name AS RackLoc, INET_NTOA(ip1.ip) AS IPv4addr, av6.string_value AS IPv6addr FROM RackObject LEFT JOIN AttributeValue AS av1 ON (av1.object_id = RackObject.id AND av1.attr_id = 4) LEFT JOIN Dictionary AS d1 ON d1.dict_key = av1.uint_value LEFT JOIN AttributeValue AS av2 ON (av2.object_id = RackObject.id AND av2.attr_id = 5) LEFT JOIN AttributeValue AS av3 ON (av3.object_id = RackObject.id AND av3.attr_id = 1) LEFT JOIN AttributeValue AS av6 ON (av6.object_id = RackObject.id AND av6.attr_id = 10000) LEFT JOIN Dictionary AS d2 ON d2.dict_key = av3.uint_value LEFT JOIN RackSpace AS r1 ON r1.object_id = RackObject.id LEFT JOIN IPv4Allocation AS ip1 ON ip1.object_id = RackObject.id LEFT JOIN Rack AS r2 ON r1.rack_id = r2.id LEFT JOIN Dictionary AS d4 ON d4.dict_key = r2.row_id ORDER BY av6.string_value DESC;"; //SQL query end here $rsSearchResults = mysql_query($sql, $db) or die(mysql_error()); $columns = mysql_num_fields($rsSearchResults); while ($i < $columns) { $meta = mysql_fetch_field($rsSearchResults, $i); if ($meta) { $out .= '"'.$meta->name.'",'; } $i++; } $out .="\n"; while ($l = mysql_fetch_array($rsSearchResults)) { for ($i = 0; $i < $columns; $i++) { $out .='"'.$l["$i"].'",'; } $out .="\n"; } // Output to browser with appropriate mime type, you choose ;) header("Content-type: text/x-csv"); //header("Content-type: text/csv"); //header("Content-type: application/csv"); header("Content-Disposition: attachment; filename=RackTablesIPv6Report.csv"); echo $out; mysql_close($db); exit; ?> <?php $localreports[] = array ( 'title' => 'Custom reports', 'type' => 'custom', 'func' => 'getOwnReports' ); function getOwnReports() { echo "<table>\n"; echo "<tr><th class=tdright>Serverlist</th><td class=tdleft><a href=\"./queries/rack_query.php\">download</a></td></tr>\n"; echo "</table>\n"; } ?>
And this is the PHP code that goes into inc/local.php. This isn't required, but it makes it easier to find all of the reports that you may wish to generate.
<?php $localreports[] = array ( 'title' => 'Custom reports', 'type' => 'custom', 'func' => 'getOwnReports' ); function getOwnReports() { echo "<table>\n"; echo "<tr><th class=tdright>Standard Report</th><td class=tdleft><a href=\"/rtreport.php\">download</a></td></tr>\n"; echo "</table>\n"; echo "<table>\n"; echo "<tr><th class=tdright>IPv6 Report</th><td class=tdleft><a href=\"/ipv6.php\">download</a></td></tr>\n"; echo "</table>\n"; echo "<table>\n"; echo "<tr><th class=tdright>Circuit ID Report</th><td class=tdleft><a href=\"/circuits.php\">download</a></td></tr>\n"; echo "</table>\n"; } ?>