Mod_Rexx HowTo

This document shows some examples of how to use Mod_Rexx to perform actions during the phases of an HTTP request to the server.


Table of Contents

Compiling Mod_Rexx
Adding a Canned Footer to Pages
Controlling Access To Document(s)
Using an index.rsp File to Control Directory Listings





Compiling Mod_Rexx

Here are the steps to compile Mod_Rexx.

  1. If necessary, modify the User Modification Section of the operating system specific makefile so that the paths to your Rexx interpreter and compiler libraries are correct.

    Note: It is not necessary to rename the makefile.

  2. Make sure the subdirectory tree from the Mod_Rexx distribution is still intact.
  3. Run the following command from the main Mod_Rexx subdirectory.
    rexx make_mod_rexx.rex orexx       <--- For Linux, Windows or AIX
           or
    rexx make_mod_rexx.rex regina      <--- For Linux or Windows
    

You should now have the Mod_Rexx binary in the appropriate location in the bin subdirectory.





Adding a Canned Footer to Pages

To add a canned footer to a set of HTML pages in a document subdirectory you need to place the following in your Apache Configuration file (httpd.conf).

<Location /mytest>
    SetHandler rexx_handler
    RexxHandler '/opt/IBMHTTPServer/rexx/footer.rex'
</Location>

The RexxHandler directive tells Apache to invoke the specified Rexx script to process each HTML file contained within the /mytest document path.

When a document is retrieved from the specified document path then the Rexx script will be invoked to read in the HTML file and add the canned footer.

http://www.myserver.com/mytest/testdoc.html

The following is an example Rexx script (footer.rex) which reads the testdoc.html document and adds the footer.

/* these are some typical Apache return codes */
OK        = 0      /* Module has handled this stage. */
NOT_FOUND = 404    /* Main document not found. */

/* get the Apache request record ptr */
r = arg(1)

body = '</BODY>'

/* try to open the main document HTML file */
retc = stream(wwwfilename, 'c', 'open read')
if retc <> 'READY:' then do
   return NOT_FOUND
   end

/* set content-type and send the HTTP header */
call WWWSendHTTPHeader r, "text/html"

/* read in the document and look for the </BODY> tag */
call on notready name seteof
eof = 0
line = linein(wwwfilename)
x = pos(body, translate(line))
do while x = 0 & eof = 0
   say line
   line = linein(wwwfilename)
   x = pos(body, translate(line))
   end
if eof = 1 then return OK

/* we found a </BODY> tag so send out the footer */
say substr(line, 1, x - 1)
call send_footer
say substr(line, x)

/* read in the rest of the document */
line = linein(wwwfilename)
do while eof = 0
   say line
   line = linein(wwwfilename)
   end

/* we are done */
return OK


/* function which indicates end-of-file */
seteof:
eof = 1
return


/* send the footer */
send_footer:
say '<br />'
say '<hr />'
say '<br />'
say '&copy; 2001 <a href="http://www.ibm.com/">IBM Corporation</a>'
say '<br />'
say '<em>Last Modified:' date()'</em>'
say '<br />'
return

Note that Rexx program files (on Unix variants) do NOT need to be marked executable in order for Mod_Rexx to execute them. If you do not mark them executable then they cannot be executed outside of the Mod_Rexx environment by accident or maliciously through the standard Apache CGI interface.





Controlling Access To Document(s)

To control access to documents or pages from a set of ip addresses you need to place the following in your Apache Configuration file (httpd.conf).

<Location /mytest>
    RexxAccessHandler '/opt/IBMHTTPServer/rexx/access.rex'
</Location>

The RexxAccessHandler directive tells Apache to invoke the specified Rexx script to check that the request originates from a specified set of ip address ranges.

When a document is retrieved from the specified document path then the Rexx script will be invoked check the client's ip address.

http://www.myserver.com/mytest/testdoc.html

The following is an example Rexx script (access.rex) which ensures that the request originates from within the range 192.168.x.x.

/* these are some typical Apache return codes */
OK        = 0      /* Module has handled this stage. */
FORBIDDEN = 403    /* Main document forbidden. */

/* get the Apache request record ptr */
r = arg(1)

/* we add the ending period so Rexx will see it as a string */
iprange = '192.168.'
if substr(wwwremote_addr, 1, length(iprange)) <> iprange then return FORBIDDEN

/* we are done */
return OK

Note that Rexx program files (on Unix variants) do NOT need to be marked executable in order for Mod_Rexx to execute them. If you do not mark them executable then they cannot be executed outside of the Mod_Rexx environment by accident or maliciously through the standard Apache CGI interface.





Using an index.rsp File to Control Directory Listings

You might be tempted to put the following into your httpd.conf file.

    DirectoryIndex index.html index.rsp

Adding the index.rsp to the DirectoryIndex statement will not produce the results you expect. In fact, it will probably cause the Apache server to crash. This is because Apache expects the files on the DirectoryIndex statement to be simple files with no special processing needs. Obviously an RSP file does not fall into this category.

In order to get the results you probably want you will need to use the RedirectMatch statement instead. Here is an example.

    RedirectMatch ^/mysubdir(.*)index.html /mysubdir$1index.rsp

This will cause a reference to index.html anywhere within the /mysubdir subdirectory tree to be replaced with a reference to index.rsp. Apache will deal with this by invoking the RSP mechanism to properly produce the index.


Valid XHTML 1.0! Copyright (C) W. David Ashley 2004. All Rights Reserved.