view release on metacpan or  search on metacpan

Motd.pm  view on Meta::CPAN

}

1;
__END__


=head1 NAME

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

=head1 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]

=head1 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.


=head1 CONFIGURATION

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

=over 4

=item B<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 B<motd>.  Therefore you can rename,delete this file from the 
specified location to disable the B<motd> without having to edit the 
httpd.conf entry and/or restart the web server.

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

=item B<RedirectInSecs> (default: 10 seconds)

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


=item B<CookieName> (default: seenMOTD)

Set the name of the cookie name 


=item B<ExpireCookie> (default: +1d, 1 day)

Set the expiration time for the cookie

=item B<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 C<$uri> along with a C<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 B<motd>,  otherwise the user is
not directed to the B<motd> but to the C<$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.

=back

   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.


=head1 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.

=over 4