innerjoin
innerjoin | perlDesk
Innerjoin Home Up Help

perlDesk install howto

Have you read about perlDesk support desk system and looking for a step-by-step guide for installing it? Happy to set up a new Linux system to try it out?

In this instance, perlDesk 1.5.5 with MySQL 3.23.51 on a newly installed RedHat 7.3.

This is an exploration of the steps needed to install perlDesk on a clean system. It is written for people who really know all this stuff but who are getting forgetful :-)

Finally, as an exploration, it is a work in progress. Revisit at intervals as improvements are woven in and bugs fixed...

Background

perlDesk is a web-based, "support", "help desk" or "trouble ticket system" written in Perl. perlDesk is a set of cgi scripts run from the webserver which manage the data in a backend MySQL database

Steps

Assumptions

The assumption made to simplify this howto is that a single machine is used for both the Apache web server and the MySQL server.

The documentation assumes that the name of the perlDesk website will by 'perlDesk.mymachine.org' and the name of the machine is 'rh.mymachine.org'.

Security

You are going to install this? How do you know it is safe? Not going to affect other parts of your system? Not open to attacks?

The simplest step is to make full use of the access controls provided by the OS and run the application under its own account. The ideal the aim to make sure that scripts:

For perlDesk under Apache, this can be implemented to a degree with a dedicated perlDesk account:

The scripts are owned by the perlDesk account and run, through suEXEC, under perlDesk. This admittedly makes life somewhat difficult.

RedHat creates accounts with a 'user' and a 'group' account of the same name. Creating 'perlDesk' will create a user account and a group of this name. Static content is set up with read access for the perlDesk and the apache account is included as a member of the perlDesk group.

Installing MySQL

Setting the hostname

Make sure the machine's host name is correct before installing MySQL, as the installation creates a couple of system administration accounts based on 'localhost' and the name returned by the hostname command.

If you install MySQL onto a machine which thinks of itself as 'localhost.localdomain' and set up the proper name later you will need to create new admin accounts and tidy away the old, hopefully unused, ones.

The name and reverse lookup details can be checked with a mix of hostname and ping.

Installing MySQL

Download the MySQL RPM's. You need the server, client and development RPM's. The MySQL version tested was 3.23.51, downloaded from www.mysql.org.

(The development RPM is needed for CPAN's DBD::mysql as it brings in the mysql.h header file)

Install MySQL with rpm

Do not set a MySQL admin password directly after the installation, this should be done later as you need to install the Perl Modules first. If you set a admin password the acceptance tests run when DBD::mysql is installed will fail.

Installating Perl

Perl 5.6.1

While release 5.6.1 of Perl is not specifically needed for perlDesk, it is a dependency of various Perl modules. RedHat 7.3 includes Perl 5.6.1 so this should not be a problem, earlier distributions will not necessarily include it. It is best to install 5.6.1 before you start downloading/installing the various modules from CPAN as the modules are installed into directories dependent on the Perl version (the modules for Perl 5.6.1 will be set up in a directory under /usr/lib/perl5/5.6.1/)

Perl CPAN

Update the Perl CPAN tools and then install the required modules (see the CPAN FAQ for info about CPAN), start by running the 'CPAN shell':

This asks a set of configuration questions giving you the option to setup CPAN manually or taking the defaults. You very probably want to do this manually as it asks a couple of critical questions:

The CPAN setup script is prompting for numbers, it gives you a numbered list and expects a number back, '4', for example, for 'Europe'

The rest of the questions can probably be left with their defaults (with the exception of the ftp and http proxy settings. If you have to access the internet through ftp or http proxies then CPAN needs to use them too).

The one application which CPAN looks for which is not in the RedHat distribution (or was not installed with my 'custom install') is lynx and it seems safe to let CPAN configure itself without it. The CPAN code can try many different ways of getting hold of the sources it needs, lynx would be used as a fallback if all else fails.

The 'WAIT' server the configuration asks about is an, admittedly basic, search engine which can be used within the CPAN script. It has nothing to do with managing timing, pauses, delays or whatever.

Update CPAN

Make sure your CPAN bundle is up to date. The first step is to get hold of the "message digest" MD5 module:

which is needed both for CPAN and perlDesk (note that both the commands and module names are case sensitive, Install won't work and install md5 won't find what you want). The "install" installs the package if it is not there and brings it up-to-date if it is already installed. The first 'install' also gets hold of the lists of CPAN's authors, package details and modules

Step two is to update the CPAN code itself:

If you don't have Perl 5.6.1, install Bundle::CPAN will try to download it as source and compile it, this may not be what you wanted....

There may be a couple of prompts to install additional modules Test::More and Test::Harness, these are things CPAN find it needs while it is in the middle of the acceptance testing, it is fine to install them.

Installing Perl Modules

Install the bundles/modules that perlDesk needs directly:

Each step will involve downloading several packages, checking them, installing and running a set of acceptance tests. Again you are likely to be prompted to install prerequisite modules (specifically for the MIME::Tools bundle). All this is handled automatically.

Note that the install DBD::mysql will fail if you do not have MySQL installed and running, if you don't have the MySQL development RPM installed (as the installation needs to find mysql.h) or if you have set a MySQL admin password.

Installing perlDesk

Downloading and unpacking perlDesk

Download perlDesk from the download page, the cut-down free version is fine to get a feel for the product. You need to move to the registered version if you want email support integrated with the package. This 'howto' currently only deals with the simple version.

Decide where you wish to install it. It is a set of Perl CGI programs; scripts which are run by the Web Server in direct response to page-download requests from a browser.

The Apache documentation includes a howto on Common Gateway Interface (CGI) programs.

The W3C security FAQ also has a section on potential problems with CGI.

The Apache server needs to know where the scripts are. Normally there is no need for the code to be installed anywhere special (like directly under the web server directories) however, in order to run the scripts under a specific perlDesk account they have to be under the 'docroot' as suEXEC understands it. The RedHat 7.3 suEXEC only runs scripts under the /var/www directory.

For this example, perlDesk was unpacked into

by means of (or from whereever you saved it when you downloaded it....). Unpacking the source creates a cgi-bin directory, an images directory and some readme, installation and licence files.

Setting File Permissions

The next step is to make sure that the permissions on the scripts are correct, the suEXEC wrapper must be able to execute the scripts and the Apache server must be able to read the static content. Out of the box, the RedHat Apache starts up running as root but then switches to the apache account (user apache, group apache). With suEXEC, the cgi scripts are run under the perlDeskuser and group specified in the configuration file

Set the ownership of the files in the /var/www/opt/perlDesk area so that they are owned the perlDesk account and perlDesk group:

and set the permissions for the files initially to read-only access for the owner and group:

The apache user account has to be added to the perlDesk group, allowing the server to be able to read the static content.

The perlDesk install file says that the .cgi files must have permissions set to 755, this should be tightened so that the scripts have just read/execute permissions for the owner:

Set the permissions on the templates to read-only for the perlDesk account:

The installation notes also say that the .tpl files in the .../cgi-bin/include/tpl directory have their permissions set to 777 if you plan to edit the templates via the admin section, this can be set to 600 so that the perlDesk account only can update the content.

Note that this is a slight security weakness and an avenue for attack. The responsibility then rests with the scripts to distrust the content of the templates, make sure that there is no way anything that might have been added to these files can possibly be executed. The cautious do not allow editing the templates via the admin section and leave with permissions as 400

So how if the perlDesk account only has read/execute access to the scripts, how it is possible to maintain them? Well, if you are cautious in the permissions setup, you are forced to be less worried about doing maintenance or development work on the scripts under root. The Unix owner/group/world basis for permissions and the suEXEC restrictions conspire against you...

Configuration

Configuring Apache

The next step is to edit the Apache configuration to tell it about the perlDesk scripts.

Where is the Apache configuration file? Run the apache httpd with a -V option and it gives its compile options. With Redhat 7.3 the Apache server config file is /etc/httpd/conf/httpd.conf.

The 'wrapper' Apache uses to run cgi scripts under dedicated accounts, suEXEC, has strict security requirements which define, or limit, a lot of the further configuration choices.

Apache allows virtual hosts to be run under specific user accounts together with the suEXEC wrapper. (If, when testing the scripts, you get 'internal server errors' back to the browser there is a good chance that suEXEC is involved. Check the suexec_log file , typically under /var/log/httpd, this is where the most detailed error messages appear)

Edit the httpd.conf configuration file and create a Virtual Host for the perlDesk application which should respond to requests to 'perldesk.mymachine.org' (and not other aliases).

The first VirtualHost provides a default configuration, this is needed to satisfy Apache's strange method of parsing the configuration data to find the right virtual host. When Apache is serving requests, if it does not find a match for a specific virtual host it takes the config for the first (rather than the default configuration), this makes the first virtual host section in the httpd.conf file special.

As the Apache Documentation says, these aliases don't start working 'by magic'. For test purposes, 'perldesk.mymachine.org' can be added to the /etc/hosts file as an alias for 'localhost', for real work this name has to be registered as a DNS entry

In this instance, we are not telling Apache to listen on different IP addresses or ports but just for a separate hostname. If the incoming hostname is 'localhost' Apache takes the first section, if it is 'perldesk.mymachine.org' then it takes the second section, if it is a further alias such as 'rh.mymachine.org' then it takes the first section as 'the default'.

The four AliasMatch statements:

Together these statements mean that Apache can handle the perlDesk package in the directory structure set up in the download. The rationale being that there'll be more patches than architecture changes.

The ExecCGI option allows scripts in a particular directory to be treated as executable, it needs to be set in order for AddHandler to work.

Addhandler tells Apache that there is module wanting to have a look at files with a .cgi extension.

Setting AllowOverride to None is just a precaution against a .htaccess appearing in the perlDesk directories and changing the configuration settings.

Configuring MySQL

Set the administrator password, which is blank by default

and where rh.mymachine.org is the name of your machine. If this latter command fails it is likely that you do not, or did not when you installed MySQL, have the hostname and reverse lookup information correct, see setting the hostname

After setting the password you need to use a -p command line option when you do any administration tasks; a -p followed by a space prompts you for the password. For example to check the status:

If you dislike that you typed passwords in on the command line (ever been hit by the Adore worm?), exit the shell so that the commands are written out to the history file, edit it (probably /root/.bash_history), and delete the 'mysqladmin' lines

Creating the perlDesk database

Create the perlDesk database by

and give the system administrator password.

On the assumption that the MySQL instance will be used for databases as well as perlDesk, create a dedicated account, here called perlDesk, using the mysql shell:

Don't forget the trailing semicolons after each command.

Don't worry about the '0 rows affected' response to the grant commands, it does not mean that it was not done.

The perlDesk account (created for you with the password 'PDPasswd') then has full rights on the perlDesk database but not elsewhere (it is an account within the MySQL database and does not link to or depend on any user account in Linux, even the one calledperlDesk. Who knows though, some time in the future there may be some form of integration... :-)

Creating the perlDesk tables

Edit the /var/www/opt/perlDesk/cgi-bin/include/conf.pl file, this contains variables for the $dbhost, $dbname, $dbuser and $dbpass. Yes, this file is potentially visible through Apache and the account details exposed. The direct, if not the best, way to prevent this tell Apache to deny access to .pl files which is what the

section in the httpd.conf does. This tells Apache not to hand out any .pl (or .txt or .tpl) files under the directory but you must not have introduced any other backdoor ways of getting to the file.

Assuming the MySQL database is on the same machine leave $dbhost as localhost, set $dbname to perlDesk, as created above, and $dbuser and $dbpass to perlDesk and its password.

Make sure the Apache server is running and using the new configuration data then run the install.cgi script through a browser:

This prompts for three major settings:

It is best to double-check these settings as you don't get immediate feedback if they are wrong. The first hint you get if you have typed the Data Path wrong is that screens built from templates (.tpl files) are not displayed on the browser - when you log in you get a blank screen.

When the import database button is pressed the script the creates the tables that perlDesk requires, progress messages are shown for each table and a finish button shown.

The final setup screen gives the licencing terms and a link to the Administrative login, however as it says you cannot logon until you have deleted install.cgi script (or moved it somewhere if you think you might need to do this step more than once while you are testing. Beware though this script has the power to delete and recreate your MySQL perlDesk tables!).

SSL Security

Configuring SSL

What else is there to do? Well, passwords are being sent from the browser to the server in cleartext. A definite weakness if administration or support work is done remotely. Sniffing the network traffic will collect the passwords as they get submitted in the logon form.

Writing the Howto...

Thanks...

There were a fair few mistakes made along the way during the writing of this 'howto' and you never really know how to fully roll back the change or install you just did.

To be certain, you need to go back to a known state, a clean system. Much deserved kudos and thanks therefore goes to the Mondo archive and restore system. It is not magic, that is, a restore does not pull information off the CD-RW drive faster than a new installation does and you do need to verify your backups, but you get the confidence that you can consistently roll back to a known state.

Navigation: [ Home ] [ Index ] [ Site Map ] [ Translate ] [ Up ] [ What's New ]
Mail: mgk@iv.mmv.innerjoin.org, 2002/07/12
URI: http://www.innerjoin.org/perlDesk/howto.html
Keywords:innerjoinorg200112, innerjoinorg, innerjoin, perldesk, install, installation, redhat, howto