NAME

Apache::ErrorControl - Apache Handler for Templating Apache Error Documents

SYNOPSIS

in your httpd.conf

PerlModule Apache::ErrorControl

<Location /error>
  SetHandler perl-script
  PerlHandler Apache::ErrorControl

  PerlSetVar TemplateDir /usr/local/apache/templates
</Location>

ErrorDocument 400 /error
ErrorDocument 401 /error
ErrorDocument 402 /error
ErrorDocument 403 /error
ErrorDocument 404 /error
ErrorDocument 500 /error

in your template (allerrors.tmpl):

<TMPL_SET NAME="webmaster_email">dj@boxen.net</TMPL_SET>

<HTML>
  <HEAD>
    <TITLE>Error <TMPL_VAR NAME="error_code"></TITLE>
  </HEAD>

  <BODY>
    <TMPL_IF NAME="404">
      <H1>Error 404: File Not Found</H1>
      <HR><BR>

      <p>The file you were looking for is not here, we must have
        deleted it - or you just might be mentally retarded</p>
    </TMPL_IF>
    <TMPL_IF NAME="500">
      <H1>Error 500: Internal Server Error</H1>
      <HR><BR>

      <p>We are currently experiencing problems with our server,
        please call back later</p>
    </TMPL_IF>

    <p><b>Time of Error:</b> <TMPL_VAR NAME="date"></p>
    <p><b>Requested From:</b> <TMPL_VAR NAME="requestor"></p>
    <p><b>Requested URL:</b> <TMPL_VAR NAME="request_url"></p>
    <p><b>Website Base URL:</b> <TMPL_VAR NAME="base_url"></p>
    <p><b>Contact Email:</b> support@mouse.com</p>
  </BODY>
</HTML>

DESCRIPTION

This mod_perl content handler will make templating your ErrorDocument pages easy. Basically you add a couple of entries to your httpd.conf file restart apache, make your template and your cruising.

The module uses HTML::Template::Set (which is essentially HTML::Template with the ability to use TMPL_SET tags). So for help templating your error pages please see: HTML::Template::Set and HTML::Template. Also check the OPTIONS section of this documentation for available TMPL_SET/TMPL_IF and TMPL_VAR params.

By default when an error 500 (internal server error) is encountered the server admin is emailed (along with the webmaster_email if its defined, see: OPTIONS). This functionality can be disabled all together with the DisableEmail option or enhanced with the EmailOn option.

Templates are looked up in the following order: the document_root is scanned for 'allerrors', 'allerrors.tmpl', error_code or error_code.tmpl. if no templates are found the TemplateDir is scanned for the same files. if no templates are found the DefaultTemplate is used and if its not set the system 'dies'.

Because so many places are checked for the templates its possible to have one global error handler and have different templates for each virtual host and also allow for defaults. It also means you can have a general catch-all template (allerrors/allerrors.tmpl) as well as single templates (i.e. 500.tmpl). Generally I just use allerrors.tmpl and use TMPL_IF's to display custom content per error message, but you can set it up any way you want.

MOTIVATION

I wanted to write a mod_perl handler so I could template error messages. I also wanted to make it extensible enough that I could have a global error handler and it would cover all the virtual webservers and have different templates for each of them - ala - the birth of Apache::ErrorControl.

TESTING

Obviously you will need the ability to test your templates, and trying to generate each error code would be a pain in the ass. So to counter this I have implemented a testing/static mode. Basically you call the handler with "/error_code" tacked on the end. You can also use this to define static error pages if you dont want the system to "automagically" determine the error_code.

to test error 401:

http:/www.abc.com/error/401

to statically configure error 401:

ErrorDocument 401 /error/401

I dont see why you would want to statically configure an error code, unless of course you run into problems for some reason and are forced to.

OPTIONS

HTTPD CONFIG PerlSetVar's

TemplateDir - the directory of your templates, this path will be used when looking up the template for the error message (looking in it for either error_code, error_code.tmpl, allerrors, allerrors.tmpl - then falling back to looking for the files mentioned before under the document_root - then falling back to using the DefaultTemplate - then 'dieing'). the TemplateDir is also passed to HTML::Template::Set as the path.
```
PerlSetVar TemplateDir "/usr/local/apache/templates"
```
DefaultTemplate - the default template file to use, can be just a filename (to be looked up under TemplateDir) or the full path to the file.
```
PerlSetVar DefaultTemplate "myerrors.tmpl"
```
MTA - (mail transit authority), basically the path to the program to send email with (i.e. sendmail, qmail-send etc). dont forget to provide any options needed for your MTA to function correctly (i.e. -t for sendmail).
```
PerlSetVar MTA "/usr/lib/sendmail -t"
```
DateFormat - you can specify the date format to use in emails and in the templates here. just provide a strftime format. this can be overrided on a per template basis with the date_format TMPL_SET param. if this isnt specified a default date format is used.
```
PerlSetVar DateFormat "%Y-%m-%d %H:%M:%S"
```
DisableEmail - if you want to disable error emails all together then set this to true.
```
PerlSetVar DisableEmail 1
```
EmailOn - if you want to recieve emails for more than just internal server errors (500) then specify an EmailOn for each using a PerlAddVar instead of a PerlSetVar.
```
PerlAddVar EmailOn 403
PerlAddVar EmailOn 500
```

Template Options

TMPL_SET

webmaster_email - setting this param enables the error email to be sent to some place other than just the server_admin, however unless this address is the same as the server admin's email an email is sent to both places.
```
<TMPL_SET NAME="webmaster_email">dj@abc.com</TMPL_SET>
```
date_format - this option overrides the DateFormat HTTPD CONF entry on a per-template basis.
```
<TMPL_SET NAME="date_format">%d-%m-%Y %H:%M:S</TMPL_SET>
```

TMPL_VAR/TMPL_IF

requestor - the requestor of the page either "user (hostname (ip))", "user (ip)", "hostname (ip)" or "ip", depending if their ip resolves or not. NB: unless you have "HostnameLookups On" in you httpd.conf you will never see the users hostname.
```
<TMPL_VAR NAME="requestor">
```
base_url - the base url of the website, i.e. http://www.abc.com
```
<TMPL_VAR NAME="base_url">
```
request_url - the full request url including arguments, i.e. http://www.abc.com/stuff/stuffed.cgi?abc=yes&no=yes
```
<TMPL_VAR NAME="request_url">
```
date - the date/time of the error (format depending on the DateFormat/date_format.
```
<TMPL_VAR NAME="date">
```
error_code - the error code, i.e. 404, 403, 500 etc
```
<TMPL_VAR NAME="error_code">
```
*error_code* - the actual error code itself is set as a param (if the param exists). if there is no TMPL_IF or TMPL_VAR defined for the error code encountered the param unknown_error is turned on (obviously only if it too is defined). personally I cant see why anyone would ever need unknown_error but ive added it here anyways.
```
<TMPL_IF NAME="404">
  Error 404 - File Not Found
</TMPL_IF>
```
unknown_error - if the *error_code* is not defined as a TMPL_VAR or TMPL_IF and there is a TMPL_IF/TMPL_VAR by the name of unknown_error it is set to TRUE (1). as mentioned above I cannot see why anyone would want this.
```
<TMPL_IF NAME="unknown_error">
  Error <TMPL_VAR NAME="error_code"> - Unknown
</TMPL_IF>
```
env_* - all env_* params are available, see HTML::Template::Set for details.
```
<TMPL_VAR NAME="env_server_name">
```

CAVEATS

This module may be missing something that you feel it needs, it has everything I have wanted thou. If you want a feature added please email me or send me a patch.

BUGS

I am aware of no bugs - if you find one, just drop me an email and i'll try and nut it out (or email a patch, that would be tops!).

AUTHOR

David J Radunz <dj@boxen.net>

LICENSE

HTML::Template::Set : HTML::Template extension adding set support

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

To install Apache::ErrorControl, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Apache::ErrorControl

CPAN shell

perl -MCPAN -e shell
install Apache::ErrorControl

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)