Flux»Projects

RackMonkey 1.2.5 Upgrade Guide

RackMonkey 1.2.5 Documentation Index

RackMonkey Version 1.2.5
©2004-2009 Will Green (wgreen at users.sourceforge.net)
Licensed under the GNU Public Licence v2.

Contents

  1. Introduction
  2. RackMonkey Files
  3. Install Dependancies
  4. Schema Update
  5. Configuring RackMonkey
  6. Upgrading the Application
  7. RackMonkey Plugins: Excel and DNS

1. Introduction

This document explains how to upgrade RackMonkey to 1.2.5. If you're doing a fresh install, please see the install guide instead. Upgrading is supported from 1.2.3 or higher. If you need to migrate from 1.2.2 or earlier, please upgrade to 1.2.3 first before performing this upgrade.

Upgrading is straightforward: but there is a schema change. Ensure you take a full backup of the RackMonkey database before upgrading.

If you're upgrading from RackMonkey 1.2.3 you should note that there has been a change in the way configuration is stored. Details are provided below.

We recommend you disable access to the RackMonkey application during the upgrade. You can do this by stopping the web server, password protecting it or turning off the execute bit on rackmonkey.pl.

Please note that the $ and # shown at the start of commands represent the shell prompt, you should not type them.

2. RackMonkey Files

Once you have obtained a copy of RackMonkey (see README) you should have a directory with the following layout: 

conf        RackMonkey and Apache configuration files
doc         Documentation for RackMonkey
perl        Perl scripts and modules
README      Read this first
sql         SQL to create the RackMonkey database
tmpl        Web interface templates
www         Web space files: images, CSS and JavaScript

3. Install Dependancies

RackMonkey 1.2.5 is the first release to officially support MySQL 5. The minimum tested server version is 5.0.22. RackMonkey 1.2.5 has revised the versions of some required software:

RackMonkey tests for the presence of a supported perl modules when run, so you will receive an error if you don't meet these requirements. RackMonkey now also requires the HTML::Entities perl module.

The easiest way to install or upgrade modules is usually with the CPAN shell. You generally need to be root in order to do this. 

# perl -eshell -MCPAN

On Mac OS X or Ubuntu Linux you can use sudo to temporarily become root (enter your usual administrator password when prompted): 

$ sudo perl -eshell -MCPAN

Once the shell has started (you may be prompted to configure it): 

install HTML::Entities

And similarly for any other modules you need to upgrade.

4. Schema Update

RackMonkey 1.2.5 includes significant schema changes from 1.2.4. The schema updates are handled by separate SQL script for each database engine. Together the updates take the schema from verion 2 to 4. If you are updating from an earlier 1.2.5 preview you only need to apply the schema version 4 update (you should already be on version 3). To check which schema you are on you can run the following on your database: 

SELECT name,value FROM rm_meta WHERE name = 'schema_version';

The version 3 schema change drops the device_app table and recreates it. This table wasn't used in prior releases, but if you manually added data to it you will need to restore it from backup after the schema change.

Each schema change is wrapped in a transaction, so if some statements fail then the database will roll back and you can continue using your existing release while you investigate the problem.

Before updating the schema be sure to take a full database backup.

Updating SQLite

Locate your SQLite database file (its location is specified in the RackMonkey configuration). Run the following (replacing DATABASE_FILE with path to your database) to move to schema version 3: 

$ sqlite3 DATABASE_FILE < sql/migration/3/migration.sqlite.sql

If the migration is successful you should see one line of output confirming you are on schema version 3: 

schema_version|3

If successful you can now move to schema version 4: 

$ sqlite3 DATABASE_FILE < sql/migration/4/migration.sqlite.sql

If the migration is successful you should see one line of output confirming you are on version 4: 

schema_version|4

Updating Postgres

Assuming your Postgres database and Postgres users are both called 'rackmonkey' you need to run the following to move to schema version 3:

$ psql -U rackmonkey rackmonkey < sql/migration/3/migration.postgres.sql

If the update was successful the output should finish with:

 name           | value 
----------------+-------
 schema_version | 3

You can safely ignore warnings of the form:

WARNING:  skipping "pg_authid" --- only table or database owner can vacuum it

This warning just indicates the rackmonkey user doesn't have permissions to vacuum system tables.

If successful you can now move to schema version 4: 

$ psql -U rackmonkey rackmonkey < sql/migration/4/migration.postgres.sql

If the update was successful the output should finish with: 

 name           | value 
----------------+-------
 schema_version | 4

As before you can ignore the vacuum warnings.

Updating MySQL

Connect to your MySQL database as a user who can create and drop tables. Make sure you're connected to the RackMonkey database. Assuming you called it 'rackmonkey' you can do this with: 

mysql> use rackmonkey;

You can then run the version 3 schema update with: 

mysql> \. sql/migration/3/schema.mysql.sql

If the update was successful the output should finish with: 

+----------------+-------+
| name           | value |
+----------------+-------+
| schema_version | 3     | 
+----------------+-------+

If successful you can now move to schema version 4:

mysql> \. sql/migration/4/schema.mysql.sql

If the update was successful the output should finish with:

+----------------+-------+
| name           | value |
+----------------+-------+
| schema_version | 4     | 
+----------------+-------+

5. Configuring RackMonkey

If you're upgrading from 1.2.3 or earlier you need to follow this section. 1.2.4 users can skip on to the rack numbering heading towards the end of this section.

Creating a Text File Configuration

RackMonkey 1.2.4 and later use a text file to store configuration information, such as the database to use. Before continuing with the upgrade process you should take a backup of RackMonkey/Conf.pm as this file is completely replaced with a new module. You should now copy conf/rackmonkey.conf-default to conf/rackmonkey.conf then use your existing RackMonky/Conf.pm module to fill in the values.

Comments in the configuration file are included with the a #. Comments must either start a line or be preceded by whitespace. Values in the configuration file cannot include spaces and configuration variables are lower case: 

Right: wwwpath = /rackmonkey/www
Wrong: WWWPATH = /rackmonkey system/www

By default this file is read from /etc/rackmonkey.conf, if you're happy to put it there, simply copy your conf/rackmonkey.conf to /etc/rackmonkey.conf. If you want to put this file in a different location you need to tell RackMonkey where to look by using an environment variable. If you're using Apache you should do this by adding the following line to your httpd.conf: 

SetEnv RACKMONKEY_CONF /path/rackmonkey.conf

Replacing path with wherever you put the rackmonkey.conf. You should then get apache to reload its configuration.

On Debian and Ubuntu:

# /etc/init.d/apache2 force-reload

On Red Hat based Linux systems (including CentOS and RHEL):

# service httpd reload

On Mac OS X 10.5 (Leopard):

$ sudo apachectl graceful

On NetBSD:

# /etc/rc.d/apache reload

On other systems kill -HUP <apache_pid> will do the trick.

Rack Numbering Direction

RackMonkey now supports setting a default numbering direction for racks. If your racks are mostly numbered from the top, so unit 1 is highest in the rack, you should set the value of 'number_from_top' to 1 in rackmonkey.conf. Don't worry, you can still override this on a rack-by-rack basis.

6. Upgrading the Application

The upgrade is now complete and the updated RackMonkey is ready to use. If you experience any problems with the upgrade you should consult the troubleshooting guide.

If you disabled access to RackMonkey prior to the upgrade (see section 1) you should now re-enable it.

7. RackMonkey Plugins: Excel and DNS

RackMonkey 1.2.5 includes two optional plugins for creating spreadsheets and looking up DNS information.

Excel Spreadsheet Export: rack2xls.pl

The current Excel spreadsheet export plugin can produce an Excel 97-2004 format spreadsheet that is readable by many applications including Microsoft Excel for Windows and Mac, OpenOffice Calc and iWork NUmbers. At present the plugin can only export a table of all devices, but further functionality will appear in future releases.

To use this plugin you need to install the Spreadsheet::WriteExcel Perl module. If you're not sure how to do this see section 2 of this document.

To enable the plugin, copy rack2xls.pl into the same directory as rackmonkey.pl, make sure it's executable (chmod 755 usually does the trick) then uncomment the plugin_xls line in the RackMonkey configuration. You should now find an 'Export XLS' button at the top of the device table views.

DNS Queries: rackdns.pl

The DNS plugin is currently very basic. It performs a query for different record types against a device name, but doesn't report errors.

To use this plugin you need to install the Net::DNS Perl module. If you're not sure how to do this see section 2 of this document.

To enable the plugin, copy rackdns.pl into the same directory as rackmonkey.pl, make sure it's executable (chmod 755 usually does the trick) then uncomment the plugin_dns line in the RackMonkey configuration. You should now find a 'Query DNS...' link next to the device name in single device view. To see the single device view simply click on the name of a device in the rack or device table views.

RackMonkey 1.2.5 Documentation Index