MOD_SCRIPTING Documentation                                ZeroToaster::HTTPD
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Preface
=======
ZeroToaster::HTTPD allows some basic scripting. You can perform basic queries 
on the request and manipulate the response or internal variables like the 
HTDOCs directory.

Queries are allowed on the CGI environment and HTTP request headers. To list 
all CGI variables perform a '#echo dump="all"' command in an SSI page. For a
list of headers refer to RFC 2616 or trace the request header with a tool 
like IPTRACE or "Live HTTP headers" (a Mozilla plugin).

Queries are connected together by boolean operators. All queries are put 
together into a ruleset file. You can define multiple ruleset files for a 
virtual host which are processed one after another until all are done. 
As usual a configuration inherits everything from his parent configuration 
(usually @default@).


Layout of a ruleset file
========================
The file is stored as plain text and read on every request. Lines starting 
with # ; ! are considered as comment. Each command is on a single line, this
simplifies processing for us. The file is divided into two sections: the 
"query section" and the "action section". A query line is either a comparison
or a boolean operator. The case (upper/lowercase) of commands and queries
is ignored. An asterisk ("*") can be used in arguments as wildcard.

--example/-------------------------------------------------
# Check if the request comes from 127.0.0.1
environment remote_addr=127.0.0.1

; This is the only query we do, switch to the "action section"
 ACTION
 
# Redirect all local request to Google
redirect=http://www.google.de
--/example-------------------------------------------------


We can perform multiple queries and concat them by boolean operators:

--example/-------------------------------------------------
# Check if the request comes from 127.0.0.1
environment remote_addr=127.0.0.1

 AND
 
# Check if the first requested language was German
header accept-language=de*

; If both checks are TRUE, send a "not found" returncode
 ACTION
set_status=404
--/example-------------------------------------------------


All lines are processed from top to bottom. Lines behind "ACTION" are 
processed sequentially so multiple actions can be performed (if useful).


List of supported boolean operators
===================================
AND
OR
ANDNOT
ORNOT

Hint: The internal boolean flag is set to TRUE at the beginning so you
      may start with the ANDNOT in any cases. See Appendix A below.


List of supported query commands 
================================

ENVIRONMENT environment-variable=argument
 Reads a certain environment variable and compares it with the argument.
 
 Examples 
 --------
 environment http_user_agent=mozilla*
 environment document_name=/somewhere/index.html
  
HEADER header-variable=argument
 Reads a certain header variable and compares it with the argument.
 
 Examples
 --------
 header referer=/old_document.html
 header cookie=logged_in=true
 header host=*google.*
 
REMOTE_IP=IP,NETMASK
 Compares the IP of the client with the given netmask. The netmask can be
 a quad dotted mask like 255.255.255.0 or a /xx mask.
 
 Examples
 --------
 remote_ip=127.0.0.0,255.255.255.0
 remote_ip=123.123.123.123,/32

 
List of supported actions
=========================
htdocs_replace=new path for htdocs
 Replaces the path to HTDOCS with a different absolute path.
 
 Example  
 -------
 htdocs_replace=/vhosts/customer/special_htdoc_dir/

htdocs_append=path to append
 Appends a path to the current htdoc directory
 
 Example 
 -------
 htdocs_append=/special/
 
set_status=number [,optional text]
 Sets the response status to something different. The optional text is
 shown in the response header only.
 
 Examples
 --------
 set_status=404
 set_status=404, Page missing
 
set_header=variable,content
 Sets a header variable in the response.
 
 Examples
 --------
 set_header=Server,Microsoft-IIS/6.0-Linux
 set_header=X-Powered-By: PHP.NET

serve_document_virtual=file
 Sends a file under the HTDOC hierarchy to the client.
 
 Example 
 -------
 serve_document_virtual=new_index.html

serve_document_file=file
 Sends a file with an absolute path to the client.
 
 Example 
 -------
 serve_document_file=c:\config.sys
 
redirect=target
 Redirects the client to a different site or document
 
 Example 
 -------
 redirect=http://www.google.com


Special features in the ACTION section
======================================
You can use environment variables on the right side of any action command
by put them between percent signs.

 Example
 -------
 redirect=http://www.zerotoaster.net/%REQUEST_URI%


Appendix A
==========
Useful examples. May the script be with you.

 1) This is for a very common situation. Your customer has a bunch of
    sites with simliar URLs but likes to force the customers to see
    only one site. But the catalog should be visible under every domain
    of the site for search engines. So we have to redirect a bunch of sites
    to one site by keeping the request URI but keep reqests for a special 
    subdirectory (/catalog/ here in this example) for the search engines.
    Remember: this scripts sees only the hosts defined in your VHOST.CFG
    
    ---<script/>---
    andnot
      environment http_host=*mainsite.com
    andnot
      environment document_name=*catalog*
    action
      redirect=http://www.mainsite.com/%REQUEST_URI%
    ---</script>---

 2) Send Google crawler a special page
 
    ---<script/>---
      header user-agent=Google*
    action
      serve_document_virtual=/google_answer.shtml
    ---</script>---
 
 
Appendix B
==========
References:
RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1
 http://www.faqs.org/rfcs/rfc2616.html
