With much fanfare, IBM began shipping its new OS/400 HTTP Server (powered by Apache) on December 15, 2000. This server is based on the alpha 2.0 version of the open- source Apache Web Server from the Apache Software Foundation (www.apache.org). While the Apache Foundation considers release 2.0 to be alpha code, IBM considers its OS/400 implementation to be a fully supported GA release and users can call for service, write APARs, and expect PTFs to be issued. Check IBM’s HTTP Server (powered by Apache) Web site (www.iseries.ibm.com/products/http/services/Apache.htm) for limitations and features not currently supported by this release before implementing the HTTP Server (powered by Apache) in a production environment.

The new HTTP Server is a prime example of how IBM is leveraging open-source applications and providing the reliability, support, and dependability that customers have come to expect with iSeries software products. IBM will not ship source code with its Apache server implementation and therefore it cannot call the server Apache, preferring instead to refer to it as the HTTP Server (powered by Apache). IBM hopes to provide superior performance and has customized the server to recognize the unique capabilities that are contained in OS/400 V4R5 and above.

For the foreseeable future, IBM will continue to support the original IBM HTTP Server in addition to the new Apache-based HTTP Server. There is no need to convert existing server instances to Apache at this time, although you will eventually need to convert to Apache. In addition, the new Apache-based server and the classic HTTP Server versions can coexist on the same machine. However, IBM has told me to expect new features first on the Apache-based version, and that some new features implemented in the Apache-based version will not be ported back to the older HTTP Server for AS/400.

The new HTTP Server is robust and a very solid implementation, but it is still an early alpha-level release. There are two areas where you should watch for enhancements over the coming months:

• IBM does not yet support the Apache Server API that lets you write or acquire third-party plug-in modules that extend the functionality of Apache.

• IBM is working to deliver a GUI that will provide an extremely easy-to-use method of configuring and maintaining the server. The current GUI implementation is rudimentary and will be enhanced in the future.

Getting Started with Apache

You must have OS/400 V4R5 installed on your machine. When OS/400 V5R1 is released, the Apache-based server will be delivered as part of the HTTP Server 5769-DG1 shipped with OS/400. You must also have TCP/IP installed and configured. Make sure that Java release 1.2 is installed on your machine. This should be delivered in OS/400 V4R5 as 5769-JV1 Option 3. Also, be sure you’ve installed the current cumulative PTF tape, and that you’ve applied the latest Java Group PTF SF99068.

The HTTP Server itself is packaged as a group PTF. You can order it from IBM at no charge as 5769DG1 Group PTF SF99035. Once you have all your materials, install these PTFs and options in the following order:

1. Install the cumulative PTF

2. Install 5769-JV1 Option 3 (if not already present)

3. Install the Java Group PTF SF99068

4. Install the Apache-based HTTP Server (5769DG1 Group PTF SF99035)

Apply these PTFs just as you would apply any other PTFs to your system. Once you’ve installed the PTFs, issue the Start TCP/IP Server (STRTCPSVR) command from a 5250 command line, and press F4 to prompt the command, as shown in Figure 1. Specify *HTTP for the server type and ADMINA for the server instance name—don’t include a preceding asterisk (*) as you would use for the *ADMIN server that is used to configure the original HTTP Server for AS/400—and then press Enter. This should start the HTTP Server’s Administration Server. Note, however, that several IGNITe/400 user group members who tested Apache along with me have encountered a problem when attempting to start the Administration Server. The error reads, You do not have the correct version of the JAVA Virtual Machine installed on your machine. If you encounter this error, you did not install 5769-JV1 Option 3. You must install this option for the Apache-based server to run.

Creating Your First Apache Server Instance

To use the Apache configuration utility, open your browser. Type the address of your Web server, specifying port 2001 (e.g., myserver.com:2001) as the TCP/IP service to contact. Note that this URL also requires that you start the *ADMIN HTTP server instance before you can access this URL. Start the *ADMIN server by typing in the STRTCPSVR command as follows:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

This should bring up the server’s administration Web page. You will be asked to log in. You are not allowed to use QSECOFR when configuring Apache server instances; instead, you must use an AS/400 user profile that has *IOSYSCFG special authority.

You will see a link on the Web page that reads IBM HTTP Server for AS/400; click on the link. On the next page in the right-hand frame, you will see a link labeled, NEW! Updated Configuration and Administration for HTTP servers (original and powered by Apache) NEW!. Click on the Administration link. As shown in Figure 2, the Apache Administration Web page will display.

Perform the following procedure to create a working HTTP Server based on an Apache server instance. Before starting, you will need to know the IP address and the port on which the server will run. The server I created in this example uses port 4431 on an

existing non-routable local IP address (192.168.1.5), but you should use port and IP address values that make sense for your shop. Here’s the steps I use:

1. Click on the Create HTTP Server link.

2. Choose a server instance to create. In the right-hand frame, you will see two radio button choices of server instance types you can create. The HTTP Server (powered by Apache)—recommended is the default selection and you should keep that selection. Click on the Next button at the bottom of the screen.

3. Name the server instance, as prompted on the next screen, by entering a one- to ten- character name. This name is the name you will refer to in the STRTCPSVR command when you start your Web server and it will be the job name for your server instance. For this example, I used the name bobapache. Click on Next.

4. Select the radio button next to the word NO to indicate that you do not wish to base this server on an existing server configuration. Click on Next to continue.

5. Choose a root path directory. You will see that IBM has created a default AS/400 Integrated File System (AS/400 IFS) root path directory for your server. In my example, that path is /www/bobapache. If you choose a location other than www, be sure that you change www to your directory of choice on all of the subsequent screens. Click on Next to continue.

6. Create a document root directory. The wizard will create a document root directory for this server instance. In my case, it created the directory /www/bobapache/htdocs. The standard default for the document root directory is a sub-directory called htdocs off your server directory, but you can change this location if you want. Click Next to continue.

7. Specify the IP address and port on which to run your server. The default setting is All Addresses, which means that your server will bind to all IP addresses it finds on your machine. Do not chose this unless you are using BIND SPECIFIC OFF on your existing HTTP Servers. If you are using BIND SPECIFIC ON for your existing classic HTTP Web servers, be sure to select a specific IP address from the list. If you do not, a conflict will occur and neither the Apache-based server nor any other HTTP Servers will start. In my example, I used 192.168.1.5. Because this address already had a server running on the default HTTP port (port 80) on that address, I specified 4431 for my port. You may use the default port 80 if there are no other HTTP Servers running on this IP address. Make your choices and click on Next.

8. Choose Combined Logs from the two choices for logging types. You will need the server to create log files. Click on Next.

9. Check the summary of your configuration choices. Congratulations—you are almost there! Review the information on the display, and if you are satisfied, click on the Finish button. Otherwise, you can click on the Back button to change any of your selections.

Start Your Servers!

You have just created an IBM Apache-based HTTP Server instance that you can start from the Administration panel. To start your server, click on the Manage HTTP Servers link from the left-hand frame on the configuration utility screen. Click on the radio button for your new server from the list in the right-hand frame. Note that a Start button will appear when you select a server that is not running. Click on the Start button. Your server should

now start. If it does not start, look at the server job log. There should be a clear message explaining why the server did not start. At IGNITe/400, we modified the STRTCPSVR command to include the -NOLASTMOD startup parameter. This is not supported by the Apache-based server. Be sure that no command line parameters are passed to the server or it will fail.

Once started, you can access your Apache-based Web server by specifying its IP address and port. In my example, I would type 192.168.1.5:4431 on my browser’s address line. You should see a default welcome screen similar to the one depicted in Figure
3.

What Next?

The wizard is a great tool, and it does a ton of extremely tedious work for you, such as creating directories, setting up the proper security and authorization for each directory and subdirectory, and creating the initial configuration file.

Take a look at what the wizard created. Figure 4 depicts the directory structure the creation wizard generated and shows some additional directories that I added to build a complete server, including the following:

• www—This is the AS/400 IFS root-level directory that serves as a placeholder to group all Web server instances you’ve created. It is created by the wizard.

• bobapache—In Apache terminology, this is the server root. It is the directory under which all objects specifically belonging to the server instance belong. It is created by the wizard.

• conf—This wizard-created directory contains the server configuration file. The configuration file is an ASCII text-based file that you can edit with any text editor.

• logs—This is where log files for this server instance will be stored. This directory is created by the wizard.

• netdata—I created this directory to store my Net.Data macros; it will include files for this instance.

• htdocs—This Apache standard directory is the root directory under which all necessary files (i.e., HTML, images) will be stored. Again, it is created by the wizard.

• private—This place-holding directory hides the actual server directory structure from users. It will hold nothing other than the /members directory in my example.

• members—This authenticated directory uses Basic Authen-tication to trigger the browser to prompt for a user ID and password, which users will need every time they try to access this directory.

Figure 5 depicts the main configuration Web page. I suggest you browse the tools on the page to get a feel for IBM’s future direction with this product. Use the GUI interface with caution. I have found the GUI to be somewhat problematic. Many of the GUI interfaces do not work as you would expect them to work and they will allow you to introduce critical errors into your configuration. There are two alternative ways to configure the server:

• Use the Edit Configuration file link found at the lower right hand side of the Configuration page. (I have had some rather unpleasant experiences with this tool. It deleted over half of my configuration file.)

• Click on the Edit Configuration File link, and highlight and copy the entire configuration (this is a more viable alternative). Paste the configuration into your favorite PC text editor. Then go out to the AS/400 IFS /www/yourserver/conf directory and rename the httpd.conf file to another name. Save your configuration file as /www.yourserver/conf/httpd.conf. IBM’s original httpd.conf file is created as a Unicode file, but saving your updated PC file to the AS/400 IFS root directory will create a US ASCII file which the server can also process correctly. You can now edit the file with your favorite PC editor (my favorite method).

Figure 6 depicts the configuration file that was initially generated by the server creation wizard and modified by hand to customize the server to meet my requirements. Here’s how the code breaks down:

• Line 2: DocumentRoot—This establishes /www/bobapache/ htdocs as the location where the server will look for documents, if no specific file is called for. When a user types the URL www.ignite400.org:4431, the document root directive points the server to the htdocs directory. This directive is created by the wizard.

• Line 3: DefaultType text/plain—Specifying text/plain instructs the server to create the header for plain-text documents when serving a page that cannot be otherwise resolved to a specific MIME type. This directive is created by the wizard.

• Line 4: HostNameLookups off—This directive turns off DNS lookups to resolve IP addresses in the server log file. DNS lookups can add an excessive amount of unnecessary server overhead. You should always turn this off unless a specific situation demands it. The directive is created by the wizard.

• Line 5: ErrorLog logs/basic_error_log—This wizard-generated directive instructs the server to create an error log named basic_error_log in the /logs directory under the server root (/www/bobapache).

• Line 6: Loglevel warn—This directive adjusts the verbosity of the messages recorded in the error logs. See the LogLevel directive explanation on the Apache Core Features Web site (httpd. apache.org/docs/mod/core.html#loglevel) for a complete definition of this directive and an explanation of the logging levels. The directive is created by the wizard.

• Line 7: ServerName www.ignite400.org—While this directive is not strictly required and therefore not generated by the wizard, it is a very good idea to code this manually created directive. The server will attempt to resolve its name from its IP address, but this process may not always work—depending on which names are associated with the IP address—and this process can result in ambiguity. It’s better to clearly define a name.

• Line 8: UseCanonicalName On—This manually created directive tells the server how to resolve self-referential URLs when the server must refer to itself. When this is set to ON, the server refers to itself by the ServerName and port.

• Line 9: Listen 192.168.1.5:4431—This instructs the server to bind to port 4431 on IP Address 192.168.1.5 upon startup.

• Line 10: Options—Various options are created by the wizard. The following options are included:

• ExecCGI—This option lets the server run CGI scripts.

• FollowSymLinks—This lets the server follow a symbolic link. In the AS/400 IFS root, you may create a link that refers to another object.

• SymLinksIfOwnerMatch—This restricts the server to following symbolic links only when the object referenced by a symbolic link belongs to the same owner as the link.

• Includes—This option tells the server to process server-side includes (SSIs).

• IncludesNOEXEC—Server-side includes are permitted, but the #exec command and #include of CGI scripts are disabled. I remove this directive to use the #exec directive in my HTML pages.

• Indexes—This option lets the server display a directory listing of a directory where the directory name is specified in the URL but no DirectoryIndex file exists.

• MultiViews—With this option, you can display content-negotiated documents. This means that a file matching all but the content type may be eligible for display. See httpd.apache.org/docs/content-negotiation.html for a comprehensive discussion of Apache content negotiation.

• Line 11: RuleCaseSense Off—Using this wizard-created directive, the user can type a URL in any case and the server will resolve it. If the rule is set to ON, then the URL typed by a user must exactly match the server file name before the server will map the URL to a path.

• Line 12: DirectoryIndex index.html—This directive instructs the server to look for a file named index.html in each directory when no file is specified in the URL and serve this file by default. The syntax lets you specify many names on the directive, such as index.html, index.htm, default.htm, and home.htm. The directive is created by the wizard.

• Lines 13 to 16: LogFormat—These wizard-created directives define logging extensions supported by WebTrends and other popular log analyzer packages. Examination of these directives reveals the capture of the type of browser, referrer, and other attributes supported in extended log analysis.

• Line 17: CustomLog logs/access_log combined—This wizard-created directive instructs the server to build a combined log file in the extended format supported by the WebTrends log analyzer and other advanced log analyzers.

• Lines 18 to 22: BrowserMatch—This set of directives extracts data from the browser and maps it to environment variables. It also provides custom instruction to the server on how to handle requests from selected browsers. The directives are created by the Wizard.

• Line 23: Alias /members /www/bobapache/htdocs/private/ members/—I created this directive to hide the true location of the /members directory. The user types a URL such as www.ignite400.org:4431/members/myfile.htm. The server will process the Alias /members and translate it to the full path /www/bobapache/htdocs/private/members. You must create this directive manually.

• Line 24: ScriptAlias /cgi-bin/db2www/ /qsys.lib/bcnd01.lib/ netdata.pgm/—You’ll need ScriptAlias for this server instance to perform CGI processing. This particular ScriptAlias enables Net.Data processing. When the user enters www.ignite400. org:4431/cgibin/db2www/mymacro.mac/main, the server will execute the program netdata.pgm in the QSYS library BCND01 and pass mymacro.mac/main as a parameter. To enable pure CGI,

I might have added a directive such as ScriptAlias /cgi-bin /qsys.lib/cgi.lib. This directive would process a URL, such as www.ignite400.org:4431/cgi-bin/ myprogram. The directive is manually created.

Directory Entries

Before I describe the directory blocks created for this server, I want to emphasize that the order in which you define directories to the server is not important. These container blocks of code could appear in any sequence and the server should work correctly.

• Lines 25 to 30—These define the server root directory. Generally, there is no access to the server root, but a directory block is mandatory. The document root directive I described earlier prevents access to this directory and forces the server to look in the htdocs directory for content. This directive is created by the wizard.

• Lines 31 to 36—These define the CGI directory that contains the BCND01.LIB Net.Data CGI library. The significant parameter in this directory block structure is the Options +ExecCGI statement. This statement lets CGI programs execute from this directory. Note also that this directory is defined under the server root directory and prior to the document root directory. This placement is important for CGI directories that exist outside the servers directory structure. You might view this as linking the directory inside of the server directory structure. The directive is manually created.

• Lines 37 to 41—These define the document root directory htdocs. Pay particular attention to the order allow, deny directive that indicates that allow rules take precedence over deny rules that follow. Note the allow from all rule that allows any user to access objects store in this directory. This directive is created by the wizard.

• Lines 42 to 55—The directory structure in these lines defines the /private/members directory and specifies that users will need basic authentication via AS/400 user profiles to access objects stored in this directory. This directory structure has several additional parameters required to enable iSeries server basic authentication (prompting for user ID and password when a user attempts to access this directory). For example, ProfileToken On is a proprietary IBM directive required to enable basic authentication. AuthName is a standard Apache directive that specifies the authentication domain (the name that pops up on the browser login window and scopes the extent of authentication). AuthType Basic is a standard Apache directive specifying that the server will authenticate using basic authentication; in other words, the server will look up a user in a user file, parse the password, and encode it using a standard encryption algorithim. I have specified that the server’s user ID QTMHHTTP be used to access the authentication objects. Finally, I have specified that the system PasswdFile should be %%SYSTEM%%, which instructs the server to call the OS/400 user profile lookup APIs.

I can also refer to an OS/400 validation list (object type *VLDL), identical to those used by the original HTTP Server for AS/400, by specifying MYLIB/VALLIST, where MYLIB is the name of a QSYS library and VALLIST is the name of a validation list stored in that library.

Just a Beginning

This article is much too narrow in scope to address the full configuration options and capabilities of the new Apache-based HTTP Server. For example, I have not touched on the directives you need to link to WebSphere or to use Lightweight Directory Access Protocol (LDAP) servers for authentication or data access, or the other hundreds of features embedded in this server.

Another development on the horizon is integrating the Tomcat Java Application Server—a free, small, and low-profile Java engine that runs servlets and JavaServer Page (JSP) files—inside OS/400 with Apache. You will have to wait for the Apache Server API to be enabled for this feature. IBM’s official response to the question of when and if users will get Tomcat support is that the topic is “under consideration”. I suspect the question should be whether IBM will support a server that competes directly with WebSphere. This is especially true now that there is an open-source version of jBoss, which provides free support for Enterprise JavaBeans (EJBs) and the full Java 2, Enterprise Edition (J2EE) specification, which requires an upgrade to the WebSphere Application Server, Advanced Edition, which is a chargeable product.

Don’t miss the ultimate resource for this server, the Apache Software Foundation Web site at www.apache.org. Use the search engine on the home page to search for tutorials, directives, and other articles and technical documentation. The site has a definite UNIX bias, which is its only downside. Don’t let that stand in your way. Contained within the Web site is a list of books on Apache, and using a third-party book when implementing Apache is as mandatory as using a road map for a cross-country trip.

Finally, the HTTP Server Documentation Web site (www.iseries.ibm.com/products/http/docs/v4r5) is the link to IBM’s official documentation for the HTTP Server (powered by Apache). I will warn you now: Go to Apache first, and then use IBM’s documentation for IBM proprietary directives. The IBM Web site is an excellent reference for Standard Regular Expressions, a powerful but cursed port from UNIX that is well-documented on the IBM Web pages.

Figure 1: Just like the classic OS/400 HTTP Server, you can start a server instance from the STRTCPSVR command.

Figure 2: The Apache administration Web page is a work in progress that will be improved in later releases.

Figure 3: When you use the wizard to generate your OS/400 Apache server instance, it automatically creates a default welcome page.

Figure 4: This is the directory structure the wizard created for my OS/400 Apache server instance.

Figure 5: Although it contains a number of options that aren’t yet functional, this IBM- provided configuration Web page will provide a valuable toolset when completed.

Display Configuration File
HTTP server: BOBAPACHE
Selected file: conf/httpd.conf
1 # Configuration originally created by Apache Setup Wizard Sun Feb 11 14:09:52 GMT+00:00 2001
2 DocumentRoot /www/bobapache/htdocs
3 DefaultType text/plain
4 HostNameLookups off
5 ErrorLog logs/basic_error_log
6 LogLevel warn
7 ServerName www.ignite400.org
8 UseCanonicalName On
9 Listen 192.168.1.5:4431
10 Options ExecCGI FollowSymLinks SymLinksIfOwnerMatch Includes IncludesNOEXEC Indexes MultiViews
11 RuleCaseSense Off
12 DirectoryIndex index.html
13 LogFormat “%h %l %u %t ”%r” %>s %b ”%{Referer}i” ”%{User-Agent}i”” combined
14 LogFormat “%{User-agent}i” agent
15 LogFormat “%{Referer}i -> %U” referer
16 LogFormat “%h %l %u %t ”%r” %>s %b” common
17 CustomLog logs/access_log combined
18 BrowserMatch “Mozilla/2” nokeepalive
19 BrowserMatch “JDK/1.0” force-response-1.0
20 BrowserMatch “Java/1.0” force-response-1.0
21 BrowserMatch “RealPlayer 4.0” force-response-1.0
22 BrowserMatch “MSIE 4.0b2;” nokeepalive downgrade-1.0 force-response-1.0
23 Alias /members /www/bobapache/htdocs/private/members/
24 ScriptAlias /cgi-bin/db2www/ /qsys.lib/bcnd01.lib/netdata.pgm/
25
26 Options None
27 AllowOverride None
28 order deny,allow
29 deny from all
30
31
32 AllowOverride None
33 Options +ExecCGI
34 order allow,deny
35 allow from all
36
37
38 AllowOverride None
39 order allow,deny
40 allow from all
41
42
43 AllowOverride None
44 Options None
45 order allow,deny
46 allow from all
47 ProfileToken On
48 AuthName “restricted stuff”
49 AuthType Basic
50 UserID QTMHHTTP
51 PasswdFile %%SYSTEM%%
52

53 require valid-user
54

55

Figure 6: Here’s the configuration file for my OS/400 Apache server; it contains many default settings, as well as several customized settings that I added to make my server work correctly.

Bob Cancilla is the IBM Rational System i Software evangelist helping to set strategy and adoption of IBM Rational application development and life cycle management software for System i customers. Bob joined IBM after over 30 years as an IT executive in the insurance industry. He was the founder of the System i eBusiness electronic user group www.ignite400.org, is the author of four books, and is an industry leader in the areas of application architecture, methodology, and large-scale integrated systems development.

 

MC Press books written by Bob Cancilla available now on the MC Press Bookstore.

 

		Getting Down to e-business with AS/400 Explains the major issues, concepts, and technologies necessary to implement an AS/400-based e-business solution—from planning for e-business to selecting an ISP. List Price $89.00 Now On Sale

Also Read

State of the Tech: Web Application Servers

Integrated Web Services Server for IBM i

Application Server Architectures