Tackle trouble tickets with the Keystone Web Problem Tracker

The Keystone Web Problem Tracker is a simple-to-use Help Desk ticket tracking application. Check out Vincent Danen's walk-through of this Web-based help desk wonder.

Do you need a central repository for sharing information regarding help desk issues or other sundry tasks? If you work in an environment providing customer support, chances are, you probably have one or need one. Such an application should be able to track customer support issues, jobs, or tasks for various groups and have a history that can be tracked.

Many such applications are available, but they cost a bundle. They aren't very portable, either; you purchase licenses for one operating system, and you can only use the product there. That forces people who prefer to use a different operating system to change in order to access the software, creating additional cost.

A Web-based application like Keystone solves the problem of portability and keeps costs down. It was designed to help a workgroup keep track of issues and jobs via a singular, shared, central, and OS-independent application. The only requirement on any OS is a Web browser. Keystone was designed specifically for IT departments where quick access to shared data, and the data's history, is a must.

In this Daily Drill Down, I’ll take a look at installing and configuring Keystone. You’ll see that it can offer your department or organization an affordable and efficient platform-independent tracking application.

Installing Keystone
You’ll need a few components prior to installing Keystone, but they’re fairly standard. You’ll need PHP version 3 or 4 installed; Keystone was written for PHP3 but seems to work fine with PHP4, as well. You’ll also need a Web server—Keystone recommends Apache—and a database server, such as MySQL or PostgreSQL. (The Keystone site indicates that testing has been done only with MySQL.)

The next step is to download Keystone from its Web site. You’ll need to agree to the author's licensing terms, which are quite odd, before you download it. In some cases, you can use it for free, and in others you’ll pay the author a yearly licensing fee. Download and save the keystone-0_74_00.tar.gz file to your top-level Web root directory. For instance, if you run your Web site from /var/www/html, save the file there and unpack it using the following to create a subdirectory called keystone/:
tar xvzf keystone-0_74_00.tar.gz

In this way, you’ll be accessing your Keystone installation by going to At this point, change to the directory keystone/conf/. Copy the keystone.conf.default and colors.conf.default files to keystone.conf.

With your favorite editor, edit the keystone.conf file. This is the primary configuration file for Keystone, and it will let you configure the most important aspects of the system.

For the most part, the defaults in the keystone.conf file should be fine. You’ll need to change a few of the defaults and make them site-specific. The configuration file is a simple PHP file so all configuration options are specified by variables. You’ll have to hop around in the file a bit to find and change these options. This line defines the base URL for your Keystone installation:
$sys_url = "";

This URL is used when generating e-mail messages. You’ll want to change it to reflect the IP address (or URL) and the base directory of your Keystone installation. For example, if you installed Keystone in /var/www/html on a server with an IP address of, you’d configure the following for the $sys_url option:

These variables define the database connection:
$sys_dbhost   = "localhost";
$sys_dbname   = "keystone";
$sys_dbuser   = "keystone";
$sys_dbpasswd = "secret";

These entries are default upon installation. $sys_dbhost is the hostname for the SQL database and $sys_dbname is the database name itself. $sys_dbuser and $sys_dbpasswd are the SQL user name and password, respectively, for access to the Keystone database.
$sys_server = "mysql";

This is the database type you’ll be using. You can choose MySQL, PostgreSQL, or Sybase. The default (and recommended) database server is MySQL.
$sys_company    = "My Company";
$sys_m_from     = "";
$sys_f_from     = "";
$sys_website    = "";
$sys_sendmail   = "/usr/sbin/sendmail";
$sys_smtpserver = "localhost";

These variables define some site-specific details concerning e-mail and your Web site. The first defines your company name, and the second defines the primary Keystone e-mail address. $sys_f_from defines the follow-up Keystone e-mail address. The next line is the URL for your Web site, and the one after that is the full path to the sendmail binary; change the path if the sendmail binary isn’t installed in /usr/sbin. Finally, $sys_smtpserver defines the SMTP server to send messages through. This is perhaps one of the most important variables in the configuration file and absolutely must be changed:
$sys_serverkey = " Keystone server";

This key is used to encrypt your login information, so it must be unique. Also, this will prevent people from using logins from other systems on your Keystone server, so it’s important that this key is unique and perhaps somewhat site-specific. It can be as long as you want, and it might be helpful to use some variation of your company name or e-mail address here.

You can alter a few more configuration options. With these two configurations, you can define where attachments can be stored and their maximum size:
$sys_attachdir = /var/www/html/keystone/attachments";
$sys_attachsiz = 100000;

The first variable determines the directory that attachments will be stored in, and the second determines the maximum size of attachments.

The colors.conf file contains color and various layout definitions so you can change the look and feel of your Keystone setup.

The next step is to create the database and tables that Keystone will use. If you’re using MySQL (which I’ll assume here), execute the following on the command line. (You’ll need to know the root password here.)
mysqladmin -u root -p create keystone

MySQL root password
If this is the first time you’ve run MySQL, you’ll have to change root’s password with the following command:
mysqladmin –u root password mynewpassword

Note that the first entry password is actually what you enter; the second entry, mynewpassword, is the new password you wish to use for your database.

When you run it as the MySQL administrator, this will create the keystone database after prompting you for your password. Next, you’ll change to the keystone/struct/ directory to import the MySQL tables. Each database type in this directory has about 34 files, and you’ll be required to import each one. If you have to enter a password each time you connect to the database, this can be a little trying. I have no idea why the author thought using 34 files instead of one was a good idea. At any rate, to make your life a little simpler, you can use the following at the Linux command line (or any other bash or csh shell):
for i in *.mysql; do mysql -u root -p keystone < $i; done

This will loop through every *.mysql file in the directory and execute the MySQL import command. Again, you’ll need to enter your password numerous times, so get ready for some repetitive typing.

When you’ve finished, you’ll be ready to log in to your Keystone system and make your configuration changes through the administrator interface.

Setting up Keystone
Next, point to your new Keystone site, which might be as simple as pointing your browser to (or wherever you have it installed). If nothing shows up, or if you get an error, you may have to edit your Apache configuration file /etc/httpd/conf/httpd.conf to allow it to use .php3 extensions, or you may have to make sure your Web server is running. To check to see if httpd is running, enter this command:
/etc/rc.d/init.d/httpd status

If you get the message httpd is stopped, run this command:
/etc/rc.d/init.d/httpd start

Check to make sure that the DirectoryIndex keyword includes index.php3 among the other index page types. It may look something like this.

You may also have to check your AddType definitions to make sure that .php3 files are being referenced. If you use PHP3, this will be the case; if you use PHP4 (which prefers .php to .php3), you may have to change things slightly, as follows:
AddType application/x-httpd-php .php .php3 .phtml
AddType application/x-httpd-php-source .phps

If you need to make these changes, restart Apache and point your browser to your Keystone site. You should see the login page. Log in with the default user admin and the password abc123. After you’ve logged in, you’ll be ready to continue configuring Keystone; you still have a number of steps to take before it will be ready for everyday use.

When you first log in, click on Other and then Password. Here, you can change the password for the admin user. This should be your very first step because the admin password is default and the same for all versions of Keystone; anyone else who has used Keystone will know the password if you don't change it immediately.

Next, click Other | Maint to open the Maintenance menu; here, you can do a lot of customization and configuration for your site. First, you should create unique login names and passwords for every person who will be using Keystone. Every person that uses Keystone should have his or her own account; this will help in history tracking.

Click on the People link. The screen that comes up allows you to add or modify users. It will give you a list of users currently on the system, along with their last login information. Before each user name are two links: Edit and Dlte (Delete). To add a new user, click on the Add A New Row button. This adds a new row to the People table in the database. (It’s unfortunate that the author chose this method, as it looks very unprofessional. In my opinion, the system should seem transparent from the database instead of looking like a front end to the database.)

At any rate, when you decide to add a new user, you’ll be asked for some basic information. You can define the login name, the full name, e-mail address, and company name. Leave the lastlog and password fields blank. You need to use the Password screen to change the user passwords, which is not intuitive but is due to the fact that the passwords are stored as an MD5 value. After you’ve added all of the users who’ll be using the Keystone system, set all of their passwords using the Password interface.

You can also define special groups for use within Keystone. By default, the two groups defined are admin and tech. Any users in the admin group will have special administrator privileges. To add or edit the groups, click on the Groups link on the Maintenance page. To add a new user to any group, simply click on the Edit link next to the group name and add the user names in the g_people column. Each user name must be separated from the next by a space.

To add a new group, click on the Add New Row button and fill in the values. The g_assign column specifies whether this group can be used when assigning slips to certain groups; answer either Y for yes or N for no.

Finally, click on the Status Codes link from the Maintenance screen. The Status Codes can be assigned to slips for your site, so you should review them to make sure they’re appropriate for your needs. By default, the status codes are Unassigned, Active, Inactive, Open, and Closed. You can add or delete as many status codes as you like.

You’ll also want to edit a few other sections in the Maintenance screen. Edit the Tables used for Version Control and Bugtracking. Here, you can define the platforms for your company products, modules, products, product versions, and resolution codes. This is the information people will use when opening up new trouble tickets, which Keystone calls slips. You should go through every section and make any needed changes to make Keystone work appropriately with your business.

Entering a slip
To see Keystone in action, log out the admin user and go back to the main login screen. At the bottom right of the screen, click on the Add A New Slip button. Here, you’ll be asked to enter your e-mail address, a category, a one-line description, and details on the problem. Enter a sample trouble ticket here and then submit the slip. At the right, click the Return To Login button and then log in as admin or any other user you defined to return to the main screen.

Click on the Slips link on the left to see a list of the entered slips. To view a slip in detail, click on the number associated with it. Here, you’ll be able to modify information on the slip. You can add follow-up information on the slip and include the amount of time spent on the problem. Keystone keeps track of time spent in minutes, so if you spent an hour, enter a value of 60.

You can also add attachments, which you can upload and have stored on the server. You can modify the slip information by changing the problem text and details or changing to whom it is assigned and the status of the slip. You can change priority information, contact information, and whether or not the problem will be publicly viewable. If you choose to change version information, you can select products, modules, etc. that you defined in the Version Control section of the Maintenance screen.

Keystone will take a little getting used to, and you’ll want to do some customization to make it work appropriately for your business or department. It certainly has the potential to be a powerful problem-tracking system capable of assigning problems to individual users or groups.

While I think it could have been made less obvious that it’s a Web front end for a database, this can easily be overlooked once you start tapping the potential of the system. With the features and functions it allows, Keystone can almost become overwhelming if you let it. Take it slowly, one section at a time, and experiment with it a little bit. Getting used to it should be simple enough, and you’ll find you have an easy-to-use problem-tracking system that can save time and money for your department or business.


Vincent Danen works on the Red Hat Security Response Team and lives in Canada. He has been writing about and developing on Linux for over 10 years and is a veteran Mac user.

Editor's Picks