Giovanni's logo Apache logo
My experience in migrating HTTP directives to Apache
1. My initial experience
2. Conclusions
3. How to use my Apache directives as an example
1. My initial experience

The material I had to start with were some articles and a sample Apache configuration file received from a friend.
I had the following systems:

  • an english language V4R5
  • an english language V5R1
  • an italian language V5R1.
I decided to:
  • discard the italian language V5R1 after finding that I just could not understand its ADMIN help text
  • do my work on the english language V5R1
  • re-test my results on V4R5

I decided not to start migrating a huge configuration. I made a very simple traditional HTTP configuration for a small application of mine, then I migrated it to Apache using the ADMIN migration wizard (I named it easy400apc).
Once it was migrated, I tried to use it, but it didn't work.
The good thing I got from it was the structure of the directory that was generated in the IFS. So I learned, for instance, where the configuration file and the log files are generated. See the following picture:

easy400apc DIR
conf DIR
httpd.conf STMF (my Apache configuration file)
hotdocs DIR
logs DIR
access_log STMF (generated by ADMIN)
basic_error_log STMF (generated by ADMIN)
welcome.htm STMF (my welcome page)

Next, I tried to use the configuration wizard in the hope to find out and fix the configuration errors or holes. The result (maybe because of my inexperience) didn't work either, and most of my previous directives were changed even if I didn't explicity request it. So I decided to go back one step to the results of my small original migration.

The only thing I could do at that point was to read, with more much attention, the latest IGNITe/400 article on the HTTP Apache Server by Bob Cancilla. I was comparing it to the example I had from my friend. This is how I started understanding the scheme of the Apache directives.
I needed an Apache dictionary to check the meaning of each directive. I went to the Apache HTTP Server Project and I found an Apache HTTP Server Version 2.0 Directives page, which was very helpful.
(Later on I found out the page where IBM documents the Apache directives available for the iSeries HTTP: you must go to page iSeries Documentation Center, go to the Quick Access Path "HTTP Server (powered by Apache)" and select "Modules and directives".)
With such supports I carefully modified manually the generated directives and after a few tests -- good heaven!-- they were working.
It was then easy add more applications by just adding similar directives.

It was time to deal with HTTP security. My champion in HTTP security is my library WEBSECURE (HTTP Security Made Easy, a very well known downloadable delivery that teaches and provides live examples about protecting web applications through user validation).
Security directives are currently not yet supported by the HTTP (powered by Apache) configuration wizard.
The example given in the IGNITe/400 article was quite understandable and it worked immediately, but it had a great drawback.
The idea there is to include the protection directives within a

<Directory> ... </Directory>
or a
<DirectoryMatch> ... </DirectoryMatch>
container (section).
  The directives of a container define the HTTP rules for all the requests that will fit the container definition.
For instance a directory container could be defined as a library. Then the pages fetched from this library (HTML source files, CGI programs, etc.) are subject to the rules (for instance, security rules) defined for such a container.
The types of container available are
  • <Directory> <DirectoryMatch>
  • <Files> <FilesMatch>
  • <Location> <LocationMatch>
Now the point here is that the <Directory> type of container does not provide the necessary granularity that may be needed for securing Web pages. Using this type of container requires security strategies at library level. For instance, CGIs not to be secured and CGIs to be secured must reside in different libraries.
This approach is not good if you already have an application library containing both HTTP secured and non-secured CGIs and you want to migrate this library from a traditional HTTP server to a new HTTP server powered by Apache. (The same talk applies to any IFS directory containing security sensitive and non-sensitive pages.)

Looking for a more granular alternative, I tried the <Files> <FilesMatch> containers, but my security directives --which were working at directory level -- did'n work any longer.

In a desperate attempt, then I tried to migrate the HTTP directives for WEBSECURE through the HTTP wizard. Though they were not working, I found out that the migration wizard was using the <Location> and <LocationMatch> containers for the translated security directives.
I decided to adopt those types of containers for my security directives, and they worked!
They have the same granularity I was used to with the original HTTP server, and I believe that this is the way to go if you need to migrate a secured application from the original HTTP server to the Apache HTTP server.

Once finished testing my configuration on V5R1 I replicated it on V4R5 and it was my pleasure to find out that it was working as well.


2. Conclusions
Here are the suggestion I would give today (October 2001) to those willing to migrate their directives from the original HTTP server to the HTTP server (powered by Apache):
  1. Use the migration wizard just to create the IFS directory and files structure needed by Apache
  2. Substitute the wizard-generated Apache directives with your ownes (must use command EDTF on file httpd.conf). If you like, you may use my directives as an example, see How to use my Apache directives as an example, later in this page.
  3. Initially do not use port 80 (my examples, for instance, listens on port 1492): this is to avoid resource conflict with other HTTP servers.
  4. Increase your directives by small sets, and test each new set by restarting your server.

3. How to use my Apache directives as an example

Click here to display my directives on a separate page.

Here are my comments:

  • PART 1
    • Server root. My server root is /easy400apc. In your directive you should specify your path (for instance /www/my1stApache). Be aware that, in my directives, /easy400apc is mentioned a number of times. You should replace it with your path accordingly.
    • Listen. This is the port number. In my case the port number is 1492 (remember Columbus?)
  • PART 2
    I would suggest to maintain these directives as they are.
    Note the directive Options ExecCGI .... If you leave it here, it would allow any CGI from whatever library to be executed. If you want to restrict CGI execution to only some libraries, then you have to remove this directive from here and to add it to the <Directory> containers related to each single library.
  • PART 3
    In this part I collected all the directives performing the original HTTP functions such as Map, Pass and Exec:
    • AliasMatch substitutes the original Map directive and also provides the original Pass function
    • Alias is a simpler way to provide both the original Map and Pass functionalities
    • ScriptAliasMatch provides the same functionality as the original Exec directive
  • PART 4
    This part is related to all the containers.
    The directives of a container define the HTTP rules for all the requests that will fit the container definition.
    I will just comment the last container for library WEBSECURE. Please compare the original HTTP directives to the (corresponding) Apache directives: you will understand by yourself, what the rule of the game is for migrating protection directives.

    Original HTTP server directives

    Protection CASE04 {
           PasswdFile WEBSECURE/CGI
           ACLOverride Off
           PostMask All
           GetMask All
           AuthType Basic
           ServerID CASE04_PROTECTION
           UserID WEBUSER01
    }

    Protect /websecp/case04try.pgm CASE04

    HTTP server (powered by Apache) directives

    <Location /websecp/case04try.pgm>
       AuthType Basic
       AuthName CASE04_PROTECTION
       PasswdFile WEBSECURE/CGI
       UserID WEBUSER01
       Require valid-user
    </Location>