Documentation

The eTicket Install Guide is an online, living book. It’s updated constantly as there are always items changed.

This book uses the following conventions:

At the top of each page should appear the versions of ets that the page refers to. This is normally (but not always) the latest version. Note: when new versions come out, the documentation may be a bit behind, or if it’s core, we will post new instructions before the actual release. Some pages apply to multiple versions, and are so noted.

Special instructions for particular versions may appear in-line. This is to prevent someone from forgetting an important step.

Additionally, we will be posting separate pages for different situations. For example, there will be a Unix Core install and a Windows core install.

If you wish to contribute to this book, please contact us with your revisions. We’ll examine those instructions and post them to this guide.

Requirements are a web server that runs PHP 5.x and MySQL 4.1 (or better).

To begin the automatic installation process you must prepair your enviroment by doing the following:

  1. Download the latest version of eTicket.
  2. Extract all files and folders from the compressed download file
  3. Upload the contents to an appropriate directory on your webserver (eg: /public_html/helpdesk/)
  4. Create a MySQL database using either command line or phpMyAdmin

All you need to do then is visit the install path that you uploaded to, for example if you uploaded to /public_html/helpdesk/ visit: http://www.yourdomain.com/helpdesk/install/ and follow the on-screen instructions.

To start the installation process you require to have “settings.php” and “pipe.php” accessible for writing. You MUST do this by changing their permissions by chmod to “666”, you can usually do this via your FTP client, or via shell or command line by doing: chmod 666 [file]

Once installation is complete you can do the following:

  • Review the contents of “settings.php” and ensure settings meet your requirements
  • chmod “settings.php” to 644, no further editing is required
  • chmod “pipe.php” to 755, must be executable
  • If you want attachments enabled you MUST chmod 666 your attachments directory
  • REMOVE the “install” directory from your server before you continue
  • Login to the admin area to configure the helpdesk
  • Setup email handling using the piping or pop3 method
  • If you intend on using the pipe method, make sure you have SpamAssassin configured first
  • Visit the eTicket Project Page.

Upgrading

eTicket can be both installed from fresh or upgraded from previous versions of osTicket or eTicket.

Upgrading has been tested with osTicket v1.3.x, but should work from osTicket v1.2 and above without a problem.

NOTICE: Always make backup your files AND database first!

If you ARE upgrading, (backup: attachements, settings.php and automail-settings.pl FIRST), remove all files and folders, upload the new ones, and finally restore any files you backed up.

Then, you MUST follow the upgrade (upgrade.php) to update the database.

IMPORTANT!! If you are upgrading from ANY version of eTicket prior to 1.7, it’s critical that you DELETE all .pl files from your eTicket directory, they pose a security risk!

Mail Handling

An important aspect of eTicket is the handling of incoming emails. There are two methods of handling incoming emails, one is the “pipe/alias” method, the second is the “pop3” method.

Each has their pros and cons, the piping method uses realtime processing of incoming emails, the pop3 method does not, however the pop3 method is best suited for people with pop3 email accounts that are not located on the local server, or cannot use the piping method.

The Pipe/Alias method (recommended)

Using this method requires the “pipe.php”.

Notice: If you DO USE the pipe method, you DO NOT require a POP3 email account.

  • Make sure the path to pipe.php on line 1 is correct
  • Make sure the %config array has the correct settings for mysql (which should have changed after running the install process)
  • Make sure you upload “pipe.php” in ascii mode (it may need to be in your cgi-bin) and CHMOD it to 755

Setting up aliases in cPanel:
Add a forwarding rule for each email in each of the setup categories to pipe.php. For example [email protected] to “|/path/to/pipe.php” (Without the quotes)

Setting up aliases with qmail:
Create/Edit your .qmail-* for the domain you wish to forward and add a forwarding rule to pipe.php For example for [email protected] .qmail-support file should contain |/path/to/pipe.php.

Setting up aliases for sendmail:
Modify your aliases file by adding support: root, |/path/to/pipe.php and run newaliases

Setting up aliases in .procmailrc:
:0 c
* ^To.*[email protected]
|/path/to/pipe.php

Note: “/path/to/pipe.php” should be the full path (eg: /home//public_html/eticket/pipe.php).

Note: Ensure you include the “|” (aka pipe) at the start of the path when using this method.

Note: Windows users may require sendmail.exe to get this to work correctly.

The POP3 Method

Note: You should only use this method if you are unable to use the above method. (ie: If your mailbox is on a different server or you can’t setup pipe mail)

  • This method requires the “automail.php” (automail php script).
  • You require a POP3/IMAP server, email address, username and password.
  • The host parameter can use the imap_open options (ie: “mail.example.com:995/ssl” access via ssl on port 995).

By default mail will only be fetched on admin or staff login, to increase fetch frequency you must use a crontab or cronjob.

Setup a cron on the local host:
Add the following to cron file normally in /etc/crontab in linix or unix based systems and adjust the time and path accordingly.
*/5 * * * * root /path/to/php /path/to/automail.php
For windows users in “Scheduled Tasks” add “c:\php\bin\php.exe c:\path\to\automail.php”

Setup a cron on a remote host:
Below are example on how to spawn automail.php from a remote server. Adjust the time and path accordingly.

# if your server supports curl:
0 * * * * curl -s -o /dev/null http://www.example.com/path/to/automail.php
# if your server supports fetch:
0 * * * * fetch -o /dev/null http://www.example.com/path/to/automail.php
# if your server supports lynx:
0 * * * * lynx > /dev/null -dump http://www.example.com/path/to/automail.php
# if your server supports wget:
0 * * * * wget -q -O /dev/null http://www.example.com/path/to/automail.php

There has been some concern over security of this file, as repeated access can cause problems. With this in mind, we advise that you rename, password protect or limit access to this file.

For example, placing this in your .htaccess file and creating a .htpasswd file, it will be password protected:

	<files "automail.php">
	AuthUserFile /home/home/.htpasswd
	AuthType Basic
	AuthName "Automail"
	require valid-user
	</files>

You can then use “http://user:pass@hostname/dir/automail.php” in the cron as per above.

Or you can limit the file to your IP address:

<files “automail.php”> Order Allow,Deny Deny from all Allow from 127.0.0.1 </files>

Note: Users can still use open.php to open a new ticket without sending any emails should you decide to use neither of the above methods.

Languages

The language file is “lang.php”, by default is “English”.

However, you are welcome to modify the language file by replacing the phrases.

eg: define(‘LANG_FATAL_ERROR’,’Fatal Error’); would become define(‘LANG_FATAL_ERROR’,’Erreur Mortelle’); in french.

The idea is that once a language file for your language you will not need to create another one.

Themes

As osTicket’s HTML code is so deeply included in the core code its difficult to fully template eTicket at the moment.

The solution is to use “themes” to style your helpdesk to suit you.

It can also be used to make language changes to existing themes which you can share with others.

Enable/Disable Captcha

Although its not recommended, due to potential spam, you can disable captcha by simply removing “captcha.php”. The rest of the script will recognise that this file is missing and will not look for it or use it.

If the security image/captcha is not working for you chances are that you don’t have PHP compiled with GD