IBM Apache Servers Needed by PHP

This is the second in a series of four articles by Brian Kelley on PHP.

Of the “big three” elements needed to support the PHP language–namely Apache, PHP, and MYSQL, the System i has used Apache since V5R1. Before this, the AS/400 used the much more bulky HTTP server from CERN that was developed by Internet pioneer Tim Berners-Lee. This open source server from the Apache Foundation is now part of the standard fare of i5/ OS entitlements. IBM even gave it a product number–5722-DG1–so it can be differentiated during the PTF process. You don’t have to order it. You just get it with the operating system. Unless you have taken pain to delete this freebie, you already have it. So, in terms of new products to install for the PHP environment, you need only PHP, but I would recommend installing MYSQL to take advantage of all the pre-written and free dynamic PHP applications that are readily available on the Internet.

i5/OS Apache comes ready to run on your System i. But, what if I told you that PHP does not really run in i5/OS? OK, yes it does. Wait, no, it doesn’t. OK, it does! Actually, it runs in the Portable Application Solutions Environment, a.k.a. PASE, a.k.a. AIX runtime. In other words, it actually thinks that it is running on a pSeries running AIX when in fact it is running on i in the pSeries or AIX environment.

PASE–The Secret Ingredient

No, it does not run in its own partition. PASE is just a phenomenal trick to let code that is compiled run on the Power chip regardless of which OS created it. PASE is really a great trick and it saves Unix developers a ton of time in bringing their applications to the System i. My suspicion is that without PASE, Zend would not have considered moving its PHP to i5/OS. Please note that PASE is not Qshell. If you have used Qshell, you know that it too looks like Unix, but it really is not. PASE is Unix runtime. Qshell is i5/OS code that pretends to be a Unix environment. PASE is a Unix (AIX) environment. With PHP, you do not really see PASE unless you choose to use MYSQL.

Because PHP does not exist in i5/OS it does not use this nice Apache HTTP server 5722-DG1 that has been on the box since V5R1. So does that mean that you have to do more work because of that? Not exactly, but it helps to understand just how PHP gets its work done. Helping all of this work of course is the nifty little Integrated File System (IFS) that IBM devised in 1995 with V3R1. Since this IFS supports any file system, both operating systems can access data and programs, and components of both operating systems obviously can talk to each other.

So, what does PHP use for HTTP and how much work is it to set up? PHP uses its own Apache HTTP server; not the same Apache server that runs in i5/OS. The integrated installation process for PHP demonstrates the deep cooperation of Zend and IBM. Once you have performed the RSTLICPGM that Erwin Earley told you about in his June 2007 IT Jungle article, PHP on i5/OS: A Whole New Stack, PHP is ready to go. Both the i5/OS Apache HTTP and the PASE Apache that is installed naturally with PHP are ready to serve Web pages. So, not only is a second HTTP server brought on board, but a new instance of HTTP called “Zend Core” is built on the i5/OS side so that the PASE server has a friendly i5/OS HTTP server instance with which to communicate.

Out of the box the installation program creates a Zend Core HTTP instance in the i5/OS. PHP does not use this instance per se. Because the i5/OS servers are visible outside of PASE, this front-end Apache server, running in i5/OS receives all of the requests from browsers. The back-end PASE Apache HTTP server talks only to PHP and to this front-end server. The servers use proxies to get their job done. The actual proxy entries are shown later in this article.

Out of the box, the preconfigured i5/OS Apache Zend Core instance talks via proxy to the single internal PASE Apache HTTP server on port 8000. Talking back to the browser, the server uses a reverse proxy scheme and it is as quick as lightening. Since IBM is positioning PHP to be able to support large workloads on the System i, though officially it suggest that WebSphere should be used for high-volume traffic, there are ways to configure multiple i5/OS HTTP servers, multiple PASE HTTP servers, and multiple PASE PHP engines to all talk harmoniously to each other. That’s a bit beyond this article, but it is documented well in this Redbook.

The fact is it just works out of the box with no sweat. As long as you set your PHP traffic (i.e., your PHP programs) to come in via port 89 of the i5/OS Apache HTTP server (Zend Core instance). From here, the back-end PASE HTTP server will get the message and send it to its PHP engine. PHP will send its results back to the PASE Apache server. The PASE Apache server sends the formatted PHP response on port 8000 back to the i5/OS Apache HTTP server, which in turn delivers the response to the requesting browser. If you need more than that, the IBM Redbook helps you do what you need to get as many instances of the different Apaches talking to each other. In most cases, the more servers, the better the performance.

So, How Do I Make This Work?

When I was working with the i5 PHP for the first time, I was intrigued that I was learning about all of this server-to-server chatter but the pragmatist in me kept wondering what I needed to do to make this stuff actually serve Web pages. I needed to know where to load my PHP scripts so that the i5/OS Apache server would get them served. I did not care as much about how to write big scripts as I did to make sure that they would run. With the PHP as shipped, the driving HTTP server for the Web, that is visible to the Web is the i5/OS Zend Core instance that is visible on port 89 of your System i’s TCP/IP ports listing. So, that is where you load your stuff. But then again, where exactly is that?

The easiest way to find where you should load your stuff is to start with a WRKLNK command. From a regular System i command panel, type WRKLNK. In many ways WRKLNK is like an old DOS DIR command.

When you type WRKLNK and press Enter, you will see the following after a few page downs:

                             Work with Object Links

 Directory  . . . . :   /
 
 Type options, press Enter.
   2=Edit   3=Copy   4=Remove   5=Display   7=Rename
   8=Display attributes   11=Change current directory ...
   
 Opt     Object link
         tmp
         user
         usr
         var
         walshltr1.lwp
  5      www
         zend
         ABOOK.HLP
         InstallShield
                                                           More...
 Parameters or command
 ===>
 F3=Exit   F4=Prompt   F5=Refresh   F9=Retrieve   F12=Cancel
 F17=Position to  F22=Display entire field    F23=More options
 

Start digging by typing the number “5” next to WWW and press Enter. On the next panel, there will be a number of other directories.

apachedft      
iaweb          
iwadft         
zendcore       

Your system will probably show different names, but one of the names will be Zend Core. Type another “5” next to Zend Core and you will see the following directories:

conf    
htdocs  
logs    

“htdocs” is the primary directory from which all Apache server instances serve files by default. one each for each configured instance. To repeat, each HTTP server instance shown above–apachedft, iaweb, iwadft, and zendcore–has its own htdocs directory. Let’s try a “5” on this directory from the Zend Core instance directory and see what is there.

index.html          
i5Toolkit_library   
myphp               
Zend_Navigator_Demo

“Index.html” is the file served by Apache from htdocs when a browser requests something from an instance via its port # (the Zend Core instance listens on port 89). The index.html file goes to your browser when you do not put in a file name. Often this is a home page document. If you type a “5” next to index.html for Zend Core, you will see its contents:

....+....1....+....2....+....3....+....4....+....5....+....6
....+....7....+.... 
 ************Beginning of data**************
<html>
<head>
<title>Welcome to Zend Core for i5!</title>
</head> 

<!-- Background white, links blue (unvisited), navy (visited),
red (active) -->
<body bgcolor='#ffffff' text='#000000' link='#0000ff' 
vlink='#000080' alink='#ff

<center><h1>Welcome to Zend Core for i5!</h1></center>
This page is the default home page for Zend Core for i5 install. 
You can also access Zend Core administrative 
interface i
</body>
</html>
 ************End of Data********************    n

This index.html file gets served by default when you access your System i with a browser and you specify port 89 with no directory or file specified. From your browser it would look something like this:

Take note to the 89 in the URL window above.

Now, let’s look at what else is in the htdocs directory for Zend Core. There is an “i5Toolkit_library” that will come in very handy for you in accessing i5 objects. There is also a “Zend_Navigator_Demo” that you may also choose to use. And yes, there it is, the innocuous “myphp” directory. Make sure you see it. This is the directory in which I uploaded a bunch of scripts for testing PHP on the i5. One of these scripts is HW.php (HW meaning “hello world”). Let’s take a look at it. But, first you must take a “5” on the myphp directory to open up the directory and then you would place a “5” next to HW.php. The simple green-screen editor is very handy for looking at files and you can also use it for making small changes. For anything of substance, use Eclipse (WDSc) or the Zend Studio that Erwin Earley spoke about in his article. If you were on my system, in which this file is actually stored, you would see:

 ************Beginning of data**************
<html>
<body>

<?php
echo "Hello World";
?>

</body>
</html>
 ************End of Data********************

Notice the PHP framing with the “nasty” semicolon at the end of the ECHO command. PHP lines love those semicolons. This file is so simple that even if you do not have it on your machine, you can type it up and load it. With option 2 of the green-screen editor, you can even make changes. If we were to run this little script on our browser, it would look like this:

Deciphering the URL–HTDOCS

Please check out the URL in the box. The http in the beginning says it is using the hypertext transfer protocol; the protocol of the Web. The 192.168.1.252 IP address is where you would place your host.domain name or your IP address. The particular IP address that you see doesn’t mean anything to anybody other than the intranet site where it exists since it is 192.168.xxx.xxx. Anytime you see this for of address, and quite frankly this non-routable class C scheme is adopted quite a bit, you cannot reach it if you tried, unless you are on that intranet.

The colon 89 says that this request comes into an HTTP server instance listening on port 89. The first slash is a path separator noting that a file or directory is coming next. As you may recall from the myphp directory, which is next on the URL line, this is where the hello world PHP script is located. This is followed by a path separator and then the file name HW.php. The capitals are irrelevant in the path.

So, why is it that this document is in the directory www/zendcore/htdocs/myphp and to reach a file in myphp you merely have to enter the directory myphp and the file name in the URL? When all System i Apache HTTP servers are set up, there is this notion called the “document root.” The document root is specified in a file called the HTTP server directives or it can also be called the configuration file. Each Apache server instance (Zend Core is just one instance) has its own set of directives in its configuration file. Two important directives (lines 6 and 7) for Apache are shown below as they exist in the Zend Core instance configuration file:

6 Listen *89
7 DocumentRoot /www/zendcore/htdocs 

Securing Internal Server Files

Line 6 is how the Zend Core instance knows to listen on TCP/IP port 89 and line 7 is how the Zend Core instance knows that its document root is www/zendcore/htdocs. The Web document root is the file system folder in which all the files and folders in a particular Website instance are stored so that they can be accessed by the public (within security limitations). In almost all servers and in the default Zend Core instance, the name for that folder is “htdocs”. On some systems it may be “public_html”. All files and folders within the document root folder are Web accessible.

So, that means by default that all folders that are not below this line of demarcation are not Web accessible. Almost all Web servers have some other stuff on their disks that the shop does not want to be public. To save these from being manipulated by PHP or even viewed, make sure your storage folders are above the web document root. The Web document root is the file system folder in which all your Website files and folders are stored. As noted, the name for that folder is typically “htdocs”, “www”, or “public_html”. All files and folders within the document root folder and its subfolders are Web accessible.

For example: “www/anyinstancename/htdocs/” could be your document root. Thus, “www/anyinstancename/htdocs/myphp/companydata/” is within the document root and therefore all files are Web accessible. But “www/anyinstancename/secretdata” is above the document root and therefore its files are not Web accessible, which is how you want it for internal folders, files and programs.

The Web Administration GUI Tool

Suppose IBM did not do all the work for you and you really wanted to have a tool that helped you manage your HTTP server instances, not just the Zend Core instance. For this, you need to use the IBM Web Administration GUI tool, which is colloquially referred to as the Admin GUI.

This tool is used to help you set up and maintain Apache HTTP server instances on your System i, and quite frankly if you are interested, it permits you to set up and maintain your WebSphere instances and applications. To access it is really easy. To make it easy to remember how to access the Web Admin GUI to set up and maintain your i5/OS Apache HTTP or WebSphere instances, I like to think of Stanley Kubrick’s 1968 movie, 2001: A Space Odyssey, because the port number is 2001. This means that 2001 is a secret port that invokes an internal invisible instance of the Apache HTTP server that hosts the Web Admin GUI on your System i.

To access the Admin GUI, click on any of the following links:

http://your-server-address:2001

http://www.greatsite.com::2001

http://192.168.10.250:2001

More than likely the first time you try this you will get the infamous Microsoft Explorer Message:

Internet Explorer cannot display the webpage

On Firefox the message is much more mundane:

Unable to Connect

If you get either of these messages, it is because you have not started your *ADMIN instance of your HTTP server. To start the *ADMIN instance, type the following from a green screen.

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

When you see message “HTTP Server Starting” at the bottom of the screen, you are on your way. Now, you can use the Admin GUI. If you fail to connect again, check your URL:

http://your-server-address:2001

http://www.greatsite.com::2001

http://192.168.10.250:2001

The first URL shown above is the form and the other two are examples. Once you type the URL of the Admin GUI in one of the forms above into your browser and press Enter on your browser–and after you sign on with your typical green screen user ID and password assuming you have adequate authority–you will get this quite handsome IBM opening menu:

Notice that this menu is used for more than the entrée to the Web Admin, but that’s all we need right now. Click on the top menu item of the i5/OS tasks menu and the first time you do this you will get a panel very similar to this:

Look at all you can do with this menu, from creating HTTP and WebSphere instances (called servers), to managing them after they are created. This is a handy menu with which to gain familiarity. For now, click the Manage tab next to setup and you will see the following:

Note the two layers of tabs on this panel. On the top layer, the Manage tab is selected and on the bottom tab, the HTTP Servers tab is selected. If your panel does not look like this, click on the proper tabs so that it does. If Zend Core is not in the Server window, pull it down and select Zend Core. The server name (instance) in the Windows is the server that you are maintaining. If you change names by pulling down the window and selecting a new name, you will usually have to wait several seconds for the screen page to refresh. Once your page looks like the one above, go down the left frame to “Tools” and select “Display Configuration File”. This is where many of the secrets of HTTP are kept. To learn more about the directives that go in this file, take a trip to the Apache Website. For now, so you can get a look at the directives that make PHP work with i5/OS display the configuration file. The center panel contents that you see will be similar to that shown below:

This is the full configuration file for the Zend Core HTTP instance. There are 30 directives. Note the proxy load modules in lines 2 through 5 and then look at the proxy and reverse proxy for communicating with the local host (i5/OS) on 127.0.0.1 and 8000 respectively. These are on lines 21 and 22. This specific configuration and this Web server instance is built automatically during the RSTLICPGM of PHP. From lines 23 to 30, note that the root file system is protected with the directory commands (line 23 to 26) and the htdocs is opened up (lines 27 to 30).

Many System i shops choose to edit the directives using the Edit Configuration File menu item below the Display Configuration File in the left frame of the HTTP panel. Others like to invoke the mini wizards within the frame to get a better feel for the changes they are making. When the left frame wizards are used, the end product is placed in the directives file.

The good news is that to run PHP right out of the box, you need not do any more configuring than what IBM has already done for you. But, having been through this article, you now know how to change the configuration if need be and you understand how much work IBM did on your behalf to make PHP as integrated with the system as it is.

See you for part three of this series when we explore the MYSQL database and how to incorporate it within the System i environment.

Brian Kelly was an IBM Midrange SE for 30 years, and has spent nearly a decade as a System i5 consultant based in Scranton, Pennsylvania. He is also author of dozens of AS/400, iSeries, and System i5 books and he serves as an assistant professor at Marywood University, which uses the OS/400 and i5/OS platform and teaches courses in the box as well. Kelly is also one of the contributing technical editors to The Four Hundred newsletter. He can be contacted through the IT Jungle contact page.

RELATED STORIES

Setting Up A PHP/Web Environment On System i: Where Do I Start?

PHP on i5/OS: A Whole New Stack

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot