This is the documentation for Release Candidate 1 or higher of the OSU Helpdesk System. It is released under the Mozilla Public License. This system is based on Bugzilla, but a great deal of functionality has been added to it to work as a helpdesk-type system. Please refer to the HelpDesk website
for user documentation and features.
If you have any problems you should visit the FORUMS
Please report bugs to bugs.osuosl.org
Feel free to add comments, questions, etc at the bottom of this page.
1) Requirements:
- IMPORTANT: intermediate knowledge of linux systems is recommended for installing Coho. This includes installing packages and configuration of mainly Apache, PHP, MySQL, and Perl. Also, you will need to be familiar with the configuration file locations for your linux distribution. Coho installation is not as simple as clicking through an installer.
- It's important that you understand package management for your OS. For example, Debian systems use "apt-get" to install packages, others have their own flavor.
- Linux: Coho Helpdesk currently only runs on Linux. It has been tested on SuSE and Debian, but should run on any RPM or .DEB based linux distribution (or even Slackware). Windows is currently unsupported. Here are requirements for your system:
- MySQL: Any version that supports TABLE LOCKING is OK, but you're better off with 4.0.x or higher.
- You must have the mysql binaries installed and accessible to your web server, even if you're using mysql on another server.
- Apache: versions 1.3 - 2.0 has been test and work
- Apache needs PHP and Perl installed.
- PHP
- php-mysql, GD extensions for PHP.
- for PHP4 you will also need the domxml extension
- Perl must be installed.
- There are required perl modules that are checked when running checksetup.pl in step 7
2) Download the Helpdesk Software package here.
- The file is in tar.gz format.
- Untar the file into your web server documents location (often htdocs on Apache Servers). If the tar file is in that directory, use
tar -xvzf package_name.tar.gz
3) Change to your root user
4) Setup a helpdesk database. Instructions
5) Setup your localconfig
- Change directory (cd command) to the root directory of your application.
- Copy localconfig.dist to localconfig using
cp localconfig.dist localconfig
- Use your favorite editor and open the localconfig file. You will need to edit the following settings
...
$mysqlpath = "/location/of/mysql";
...
$webservergroup = "www-data"; #you may need to change this. Debian is "www-data", SuSE is "www", RedHat is "apache", etc.
...
$db_host = "hostname of your database server";
$db_port = 3306;
$db_name = "name of your database"; # name of the MySQL database
$db_user = "user name for your helpdesk database"; # user to attach to the MySQL database
...
$db_pass = 'password for your helpdesk database';
6) Setup your definitions file
- Change directory to <helpdesk-root>/php_auth
- Change cp defines.php.dist to defines.php using
mv defines.php.dist defines.php
- Use your favorite editor and open the defines.php file. You will need to edit the following settings:
...
define ("INSTALL","/<url-of-your-app>/");
...
define ("DB_NAME","your-database-name");
define ("DB_UNAME","your-database-username");
define ("DB_PWD","your-database-password");
define ("DB_HOST","your-database-host");
...
*If you're using LDAP you should edit the following sections*
define ("LDAP_HOST","your-ldap-server"); #example: "ldap.blah.com"
define ("LDAP_HOST_2","your-backup-ldap-server"); #example: "ldap2.blah.com"
define ("LDAP_PORT",your-ldap-server-port); #example: 3268
define ("SUFFIX","your-ldap-search suffix"); #example: "oregonstate.edu"
define ("BASE_DN","your-ldap-base-dn"); #example: "DC=oregonstate,DC=edu"
define ("BIND_DN","your-ldap-bind-dn"); #example: CN=bind\\, hd,OU=SSG Accounts,OU=Users,OU=USE,DC=TS,DC=oregonstate,DC=edu
define ("BIND_PWD","your-authentication-password");
7) Begin installing the application:
To setup your helpdesk system, you will run a script that will check your setup to make sure that you have the right perl packages and other things installed properly. To run this script, use
The script will run through and check your current setup to see what the system needs, and if you have it installed. My first run on SuSE looks something like:
Checking perl modules ...
Checking for AppConfig (v1.52) not found
Checking for CGI (v2.88) ok: found v3.00
Checking for Data::Dumper (any) ok: found v2.121
Checking for Date::Format (v2.21) not found
Checking for DBI (v1.32) not found
Checking for DBD::mysql (v2.1010) not found
Checking for File::Spec (v0.82) ok: found v0.86
Checking for File::Temp (any) ok: found v0.14
Checking for Template (v2.08) not found
Checking for Text::Wrap (v2001.0131) ok: found v2001.09291
The following Perl modules are optional:
Checking for GD (v1.20) not found
Checking for Chart::Base (v0.99) not found
Checking for XML::Parser (any) ok: found v2.31
Checking for GD::Graph (any) not found
Checking for GD::Text::Align (any) not found
If you you want to see graphical bug charts (plotting historical data
over
time), you should install libgd and the following Perl modules:
GD: perl -MCPAN -e'install "GD"'
Chart 0.99b: perl -MCPAN -e'install "N/NI/NINJAZ/Chart-0.99b.tar.gz"'
If you you want to see graphical bug reports (bar, pie and line charts
of
current data), you should install libgd and the following Perl modules:
GD: perl -MCPAN -e'install "GD"'
GD::Graph: perl -MCPAN -e'install "GD::Graph"'
GD::Text::Align: perl -MCPAN -e'install "GD::Text::Align"'
Bugzilla requires some Perl modules which are either missing from your
system, or the version on your system is too old.
They can be installed by running (as root) the following:
perl -MCPAN -e 'install "DBD::mysql"'
Minimum version required: 2.1010
perl -MCPAN -e 'install "DBI"'
Minimum version required: 1.32
perl -MCPAN -e 'install "Date::Format"'
Minimum version required: 2.21
perl -MCPAN -e 'install "AppConfig"'
Minimum version required: 1.52
perl -MCPAN -e 'install "Template"'
Minimum version required: 2.08
You can see that I am missing a bunch of modules, both required and suggested. The suggested ones are pretty much required anyway if you want graphing, LDAP, or some other functionality. It tells you the scipts you need to run to install the modules. For example, to install the "GD" perl module run
perl -MCPAN -e'install "GD"'
- If, at any time, you get an error like
then you need to install the related development RPM or Debian package (for X11, it would be xfree86-devel, png means png-devel, etc)
- If you get an error like
no such group: www-data at checksetup.pl line 1144
then you need to back to step 4 and change the webserver group information
7b) Once you have all the packages installed, rerun the check
If your setup is right, and packages are right, you should now see a bunch of tables being created on your database, and your should be walked through setting up the admin account.
8) Setup Apache to run Perl properly.
In your *httpd.conf your will definitely need to add the ExecCGI option. Here's a sample:
Options Indexes -FollowSymLinks +Includes MultiViews ExecCGI
Also, change your
AddHandler property to have
.cgi Sample:
AddHandler cgi-script .cgi .sh .pl
Finally you should have your overrides to
limit
9) Setup HelpDesk parameters
The HelpDesk is now installed, but you will need to do some configuration. Log in with your new admin account. Some of the major things are:
- Create a new helpdesk and remove the "TestProduct" helpdesk. Do this at "helpdesks" -> "add a new helpdesk". Once added, you need to revisit the edit page for that helpdesk to edit categories, affiliations, and group access controls not previously shown on the add page.
- Visit "Manager Tools" -> "Add Department" and add at least one department.
- If using any modules (KB, Cal, Inven) you should create groups to match the settings in php_auth/defines.php on lines 17, 25, and 28. By default the two groups needed are techs and managers, but you may change these to whatever you wish as long as the settings align.
php_auth/defines.php ...if(USING_KB){
define("KB_NAME","cohokb");
define("KB_UNAME","buchanae");
define("KB_PWD","AdMathCot1");
define("KB_HOST","localhost");
$db_groups = array("create" => "techs", "release" => "managers", "admin" => "admin");
$kb_groups = array("create" => "User", "release" => "Super-User", "admin" => "Administrator");
}
if(USING_CAL){
define("CAL_NAME","");
define("CAL_UNAME","");
define("CAL_PWD","");
define("CAL_HOST","localhost");
$groups = array("users" => "techs", "admin" => "admin");
}
if(USING_INVEN){
$inven_groups = array("1" => "techs","2"=>"managers");
}...
10) That's it
For other issues, please refer to the this link for outstanding issues affecting this release:BUGS
Posted by
In RC 1.2, if you aren't using LDAP (I'm not), you'll run into problems if you only follow these directions, as the code will still attempt to initiate LDAP authentification.
Over in the bugs section (http://bugs.osuosl.org/browse/OHD-6
) there was a similar issue to the output you get, with an easy solution:
Comment out line 24 in php_auth/login.php
//$ldap_info=ldap_auth($_POST'user',$_POST'pass');
I found that I also had to comment out all instances of "use Net::LDAP" in CGI.pl, and I restored the original DBNameToIdAndCheck() in globals.pl (it's still there, just commented out).
It now seems to be working for me.
Hope that helps someone!