From DclWiki

Contents 1 Installation Instructions for Double Choco Latte 1.1 Server Requirements 1.2 Client Requirements 1.3 Setup 1.3.1 Source Files 2 E-Mail Gateway Installation 2.1 Operational Behavior 2.2 Prerequisites 2.3 Gateway Installation 2.4 Configuration for Postfix MTA 2.5 Configuration for Sendmail MTA 2.6 Configuration for Exim 3.x MTA 2.7 Configuration for Exim 4.x MTA 2.8 Configure the Gateway Script 2.9 Configuring DCL for the Gateway 3 FAQ 3.1 I installed DCL on a Windows NT Server running IIS and PHP. When I try to login, I get a message saying "Could not verify session." What could be wrong? 3.2 I went through the setup screen and configured DCL for our projects. Now when I try to enter a work order or ticket, the priorities and severities are empty after I select a product. 3.3 When trying to login to DCL, I get the login screen with a message that says "Could not verify session". I'm using IE. 3.4 After installing the files and setting up the database, I get this error when I go to index.php: Fatal error: Call to undefined function: setdbformat() in /path/to/datetime.php on line n. 3.5 No databases are listed in the drop down menu of the "General configuration" page while running the /dcl/setup script. 3.6 The installation went fine, but when logging in for the first tiem as sa/sa, I receive "Invalid Login".

Installation Instructions for Double Choco Latte

These items _must_ be setup, configured, and operating properly for Double Choco Latte to function properly. We cannot provide guidance for configuring this software. The accompanying documentation for each package does a good job anyway.

Server Requirements

• Operating System which supports PHP/PostgreSQL/Apache
  • Linux
  • Windows NT, 2000 - should also work in 9x, Me as long as PHP works
  • I have gotten some e-mails in the past suggesting it works in *BSD and Solaris as well
• Apache Web Server, IIS, or any web server supporting PHP
• PHP
• One of the following RDBMS
  • PostgreSQL
  • MySQL
  • Microsoft SQL Server
  • Sybase Adaptive Server Enterprise

Client Requirements

JavaScript enabled browser. Sorry that this is a requirement, but if you do not want something that is (fancy, evil) such as JavaScript, you should probably look at some of the other packages available for free such as:

• Mantis
• Request Tracker
• Bugzilla
• Jitterbug

Setup

Starting with version 0.9.4, DCL has a web-based install/upgrade interface. It was derived from the code used for XOOPS setup. Be sure to backup your database prior to running the upgrade! It is much better to be safe than sorry in this respect.

Point your browser to http://127.0.0.1/where.did.I.install/dcl/setup to begin the wizard. It will ask you for your database connection information. If you use a database user that is capable of creating databases and this is a new installation with no database, the setup wizard will attempt to create the database for you. If the user you will be connecting as through DCL does not have this privilege, you will need to manually create your database. See your documentation for your SQL server to learn how to do this if necessary.

After you are finished with the setup wizard and have verified this install is working properly, delete the setup directory! It is an obvious security risk to leave this directory intact. Another option is to protect the setup directory with web server security (such as .htaccess and .htpasswd files for Apache). Removing the setup directory is highly recommended, however.

Source Files

• Put the DCL source files under the web server DocumentRoot. We used a subdirectory called 'dcl' for testing. You may also create a virtual directory for DCL. See the documentation for your web server for instructions on how to accomplish this.
  • You don't have to move the entire tree over to the web server, and may not want to. Files and directories you should exclude are: INSTALL, README, TODO, ./inc/config.php.default, ./debian, ./docs, ./contrib, and ./scripts.
• Install the system (http://localhost/dcl/setup/) as documented above. If upgrading, backup your database before running setup!
• Access the system by using the URL you just created (i.e., http://localhost/dcl/).
• Login as sa with password sa.
• Change sa password through the Admin...Change Password menu option.
• Go to Admin...System Setup and follow the steps to set up the system.

E-Mail Gateway Installation

Starting with version 20011208, DCL includes an e-mail gateway in the contrib/gateway directory of the distribution. The gateway is a PERL script that expects to receive e-mail piped to it from a MTA such as Sendmail, Postfix or Exim. This section will attempt to provide some direction for installation and configuration of the gateway, along with a basic overview of how it works.

Operational Behavior

The steps involved in bringing tickets in through the e-mail gateway can be summarized as follows. For the sake of providing examples, we will assume Double Choco Latte (DCL) is the product.

• Issue reporter sends e-mail to dcl-support@mydomain.com
• MTA for mydomain.com recognizes dcl-support as an alias and forwards it to the PERL script
• PERL script sections the e-mail into headers, body, and attachments.
  • Defaults set from DCL config are: priority, severity, and status
  • From: is sectioned into name and e-mail address and inserted into contact and contact e-mail respectively
  • To: is sectioned to retrieve product name. The address is formatted as <product_abbreviation>-support@mydomain.com. The script retrieves the product abbreviation, looks it up in DCL, and sets the product ID for the ticket. If the product is not found, the script will exit with an error message.
  • The e-mail subject is inserted into the summary
  • The e-mail body is inserted into the issue field, minus any attachments
• Using information in the headers, body, and DCL configuration, a ticket is constructed
• The ticket is created and the files are "attached" to it
• Optional e-mail response is sent to originator of e-mail
• Responsible and watchers are notified of the new ticket
• Optionally, responses to the ticket autoresponse e-mail are appended as ticket resolutions (TODO: this feature is not yet implemented)

Prerequisites

This has been used on a PERL installation as old as 5.005_03. PERL modules required for this to operate include:

• MIME::Base64
• MIME::Parser
• MIME::QuotedPrint
• File::Basename
• DBI
• DBD driver for your SQL server (DBD::mysql or DBD::Pg)
• Net::SMTP

You can install these packages from the CPAN shell (perl -MCPAN -e shell) by doing install <packagename> (e.g., install DBI)

Gateway Installation

• Place the dcl-gateway.pl script in a suitable location (mine is in /etc/postfix). The Postfix daemon must have read access to the directory and the file should have executable permissions.
• Create a directory for the gateway script to use for temporary storage (I used /usr/local/dcl/tmp). The MTA daemon should have read, write, and execute for the directory. It also needs to be able to read, write, and execute directories where the DCL attachments are stored (e.g., /usr/local/dcl). If this is not done correctly, any file attachments in the e-mail will not be attached to the ticket!

Configuration for Postfix MTA

• Edit the /etc/aliases (or /etc/postfix/aliases) file.
  • Add aliases for each product you would like to route to the gateway.
  • Aliases should pipe to the gateway script
    • dcl-support: "|/path/to/dcl-gateway.pl"
  • Run the newaliases command
  • Restart the postfix daemon (postfix reload)

Configuration for Sendmail MTA

• Sendmail requires executable files be placed or linked in /etc/smrsh for security. Either ensure the dcl-gateway.pl file is in this directory or create a symbolic like from the file to the /etc/smrsh directory.
• Edit the /etc/aliases file.
  • Add aliases for each product you would like to route to the gateway.
  • Aliases should pipe to the gateway script
    • dcl-support: "|/path/to/dcl-gateway.pl"
• Run the newaliases command
• Restart the sendmail daemon (/etc/rc.d/init.d/sendmail restart)

Configuration for Exim 3.x MTA

TODO

Configuration for Exim 4.x MTA

TODO

Configure the Gateway Script

The only configuration that has to be done in the script is setting up your database settings. This should match how you have DCL set up. If you are using multiple domains and want to receive e-mails for each domain, you will need to create a copy of the gateway script for each domain. Your aliases will point to the appropriate script depending on the product in the To: address.

Configuring DCL for the Gateway

The Admin...System Setup...Configuration page now has a section for configuring the e-mail gateway.

• e-Mail Gateway for Tickets Enabled - must be checked in order for tickets to be created. Otherwise, an error will occur and the MTA will reject the e-mail.
• Send Auto-Response to Sender Upon Receipt - If checked, a quick e-mail is sent to the originator of the e-mail informing them that the ticket was entered successfully into DCL.
• Auto-Response e-Mail Address - The address to use in the From: field of the auto-response e-mail. Must be set to the same as your support address if the Allow Replies to Append Ticket Resolutions feature is to be used.
• Allow Replies to Append Ticket Resolutions - if the ticket issuer responds to the auto-response e-mail, the resulting e-mail will be appended to the ticket as a ticket resolution.
• Gateway Ticket Status - the status to assign tickets created by the gateway
• Gateway Ticket Priority - the priority to assign tickets created by the gateway
• Gateway Ticket Severity - the severity to assign tickets created by the gateway
• Decode File Path for Ticket Attachments - the path to the temporary file area for decoding attachments.

Also, the e-Mail SMTP Server section is used to configure the SMTP server used for outgoing e-mails. If the SMTP Enabled option is deselected, the responsible person for the ticket and the watchers will not receive e-mail notifications of the ticket's entry. Regardless of the Enabled option, the Server, Port, and Connection Timeout settings are still used for auto-response e-mails.

FAQ

I installed DCL on a Windows NT Server running IIS and PHP. When I try to login, I get a message saying "Could not verify session." What could be wrong?

More than likely, you are running PHP as a CGI handler. A known bug in IIS prevents cookies from being set properly if they are sent in the header along with a Location: header for redirection. The best fix at the moment is to change the redirMethod to meta.

I went through the setup screen and configured DCL for our projects. Now when I try to enter a work order or ticket, the priorities and severities are empty after I select a product.

You need to add your new priorities and severities to the appropriate attribute sets. Go to Admin...System Setup...Attributes. Click on the View link for the set you want to modify. For each attribute, click on the Map link and use the forms to modify the available items and, in the case of priorities and severities, their weight (display order) in the drop downs.

When trying to login to DCL, I get the login screen with a message that says "Could not verify session". I'm using IE.

Due to a strange bug in IE, you need to ensure you specify the trailing slash of the URL (i.e., http://host.com/dcl/ and not ~http://host.com/dcl ). I assume this is a bug in IE since other browsers can cope with it just fine. This may be due to the way the server handles the response. A server does not need to handle them in the same way; being able to use a final '/' seems to be supported by most web servers, but doesn't need to be. Check the server configuration to make sure it's not interfering somehow.

After installing the files and setting up the database, I get this error when I go to index.php: Fatal error: Call to undefined function: setdbformat() in /path/to/datetime.php on line n.

The problem is caused by the Alternative PHP Cache (APC) being loaded. This error should no longer happen (since 20010923 release). If you have the issue with a newer release, please report it.

No databases are listed in the drop down menu of the "General configuration" page while running the /dcl/setup script.

Make sure that you have installed the PHP module for the database you wish to use.

The installation went fine, but when logging in for the first tiem as sa/sa, I receive "Invalid Login".

You may need to change your cookie settings. Try opening the inc/config.php file and change the DCL_REDIR_METHOD to meta. It is php by default. This setting alters how DCL sets the cookie after authentication.

---

If all else fails beyond repair, feel free to contact us.

mailto:dcl-support@gnuenterprise.org