Carlos Ramirez > Apache-Motd-1.00 > Apache::Motd

Download:
Apache-Motd-1.00.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.00   Source  

NAME ^

Apache::Motd - Provide motd (Message of the Day) functionality to a webserver

SYNOPSIS ^

 in your httpd.conf 

 <Directive /path/>
   PerlHeaderParserHandler Apache::Motd
   PerlSetVar MessageFile       /path/to/motd/message 
   PerlSetVar CookieName        CookieName [default: seenMOTD]
   PerlSetVar ExpireCookie      CookieExpirationTime [default: +1d]
   PerlSetVar RedirectInSecs    N [default: 10]
   PerlSetVar SupportCookieLess (1|0) [default: 1]

DESCRIPTION ^

This Apache Perl module provides a web administrator the ability to configure a webserver with motd (Message of the Day) functionality, just like you find on UNIX systems. This allows custom messages to appear when visitors enter a website or a section of the website, without the need to modify any webpages or web application code! The message can be a "Message of the Day", "Terms of Use", "Server Going Down in N Hours", etc. When applied in the main server configuration (i.e. non <Location|Directory|Files> directives), any webpage accessed on the webserver will redirect the visitor to the custom message momentarily. Then after N seconds, will be redirected to their originally requested URI, at the same time setting a cookie so that subsequent requests will not be directed to the custom message. A link to the requested URI can also be provided, so that the user has the option of proceeding without having to wait the entire redirect time. (See motd.txt example provided in this distribution)

The intention of this module is to provide an alternate and more efficient method of notifying your web users of potential downtime or problems affecting your webserver and/or webservices.

CONFIGURATION ^

The module can be placed in <Location>, <Directory>, <Files> and main server configuration areas.

MessageFile

The absolute path to the file that contains the custom message.

 i.e. MessageFile /usr/local/apache/motd.txt

If the file is not found in the specified directory all requests will not be directed to the motd. Therefore you can rename,delete this file from the specified location to disable the motd without having to edit the httpd.conf entry and/or restart the web server.

See MessageFile Format for a description how the message should be used.

RedirectInSecs (default: 10 seconds)

This sets the wait time (in seconds) before the visitor is redirected to the initally requested URI

CookieName (default: seenMOTD)

Set the name of the cookie name

ExpireCookie (default: +1d, 1 day)

Set the expiration time for the cookie

SupportCookieLess (default: 1)

This option is set by default to handle clients that do not support cookies or that have cookies turned off. It performs an external redirect to the requested $uri along with a ct=1 query_string to test if the client accepts cookies. If the external redirect successfully sets the cookie, the user is presented with the motd, otherwise the user is not directed to the motd but to the $uri.

Future versions will correctly support non-cookie clients via URL munging.

Setting this option to 0 is ideally used for when you are totally certain that all your visitors will accept cookies. This is usually much faster since it elminates the external redirect. ***Use with caution. Cookieless clients will get the motd message and *only* the motd if this option is false.

   Example:

   <Location />
    PerlHeaderParserHandler Apache::Motd
    PerlSetVar MessageFile /proj/www/motd.txt
    PerlSetVar CookieName TermUsage
    PerlSetVar RedirectInSecs 5
   </Location>


  The example above, sets a server wide message (/proj/www/motd.txt) that
  sets a cookie called TermUsage which expires in one day (default value)
  and redirects the user to the original URI in 5 seconds.

Message File Format ^

The text file should at least include the folowing tag variables. These tags provide neccessary information to allow redirection to the original request and the time (in secs) before the redirection take place.

VAR_URI

This tag will be replaced with the requested URI.

Recommended usage:

<a href="<VAR_URI>">click here to proceed</a>

The above example provides a link to the original requested URI, so that a user can click and bypass the time redirect.

VAR_REDIRECT

This tag will be replaced with the value set in RedirectInSecs. Which can be used in the meta tag for redirection.

Example:

   ...
   <head>
   <meta http-equiv="refresh" content="<VAR_REDIRECT>;URL=<VAR_URI>">
   ...
   </head>
   ...

The custom message should at least contain a redirect (using a meta tag) and a link to allow users to bypass the redirect time (for impatient users and as a courtesy). Omitting these will result in the page not redirecting the user to the initially requested page.

NOTES ^

Bypassing Motd

<Directory> and <Location> configuration settings propogate to sub-directories and sub-locations matches. One way to turn off the motd on a motd'd sub-directories and locations is to do the following:

 <Location />
  PerlHeaderParserHandler Apache::Motd
 </Location>

 ## Bypass motd on locations under /foo
 <Location /foo>
  PerlHeaderParserHandler Apache::Motd:OK
 </Location>

 **Example courtesy of Jerrad Pierce

Logging

There are two times Apache::Motd logs non-error messages to the apache error_logs. One instance is when the motd is displayed and the other is when the motd is bypassed because cookies were rejected.

 ## motd displayed sample entry
 [Wed Dec 13 14:17:57 2000] [error] Motd::Display for URI: /requested/doc.html from $remote_ip

 ## motd is bypassed sample entry
 [Wed Dec 13 14:17:57 2000] [error] Motd::Bypassed by $remote_ip

These entries can by used to gather statistics about how many times the motd is being encountered and how many times it's being bypassed.

BUGS ^

Minimal Support for cookie-less clients

Browsers that have their cookies turned off or that do not support them will not see the motd. I hope to implement a URL-based solution so that Apache::Motd will support these browsers correctly. So in the meantime, you must find other ways of relaying your urgent messages to your visitors.

No error checking on the custom message

The template is not checked for the neccessary information required for the redirection to work properly, i.e. usage of <VAR_URI> and <VAR_REDIRECT>. Therefore not using the available tags as described will result in unpredictable behavior.

REQUIREMENTS ^

 L<mod_perl>, L<Apache::Cookie>

CREDITS ^

Fixes, Bug Reports, Optimizations and Ideas have been generously provided by:

Jerrad Pierce <jpierce@cpan.org> - no-cache pragma on motd file - motd bypass on sub-directories and location matches - no-cookie browser problem bug report

Marion Gazdak - Missing server port bug. Fixes problem when testing on the non-standard port (80) - Check for existance of motd file specified in MessageFile. Removing motd file from location specified in MessageFile disables motd. Now works as advertised.

AUTHOR ^

 Carlos Ramirez <carlos@quantumfx.com>

COPYRIGHT ^

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

If you have questions or problems regarding use or installation of this module please feel free to email me directly.

syntax highlighting: