Configuring and Managing MPE/iX Internet Services > Chapter 9 Apache for MPE/iX

Major Components

	MPE documents
	Complete PDF
	Table of Contents
	Glossary
	Index

	E0802 Edition 6
	E0701 Edition 5
	E0400 Edition 4 ♥

The major components for Apache are the web server program (HTTPD), the job stream file which runs the HTTPD program (JHTTPD), a set of configuration files for enabling Apache features, the htdocs directory containing HTML pages, the logs directory, and the cgi-bin directory. Apache also comes with a full, on-line manual set.

HTTPD is the Apache web server program. "HTTP" stands for the protocol used between the client browser and the Apache web server. "D" stands for daemon, a system program which automatically handles certain system operations. The HTTPD web server program intercepts an incoming request from the browser, interprets and handles the request, then delivers output in the form of an HTML page to the client.
The HTTPD program file resides in the /APACHE/PUB directory and is linked with Privilege Mode (PM) capability. Because HTTPD is a privilege mode program, it must run under an MPE account and group which both have PM capability. PM is necessary for Apache to use port numbers less than 1024 (privileged ports). By default, Apache uses port 80.
JHTTPD is a job stream file which runs the Apache web server as a standalone process. This file also specifies the system timezone and the location of the global Apache configuration file, httpd.conf. JHTTPD resides in the /APACHE/PUB directory.
The configuration files tell the HTTPD server program where to find files, which files and directories can be accessed, who can access them, and the location of executable programs on the server. These files give you the flexibility of having the web server do only what you want it to do. These files reside in /APACHE/PUB/conf.
The htdocs directory contains the public documents, images, and data to be served to clients. The htdocs directory and the directories below it are available to anyone accessing your web server.
The logs directory contains log data of both web server accesses and of errors.
The cgi-bin directory contains CGI scripts which are executed by Apache on behalf of its clients.
The bin directory contains a set of scripts and programs contributed by the Apache Software Foundation. They are included as examples only and are not supported by HP.
The Apache manual set, residing in /APACHE/PUB/htdocs/manual, describes the entire Apache feature set and the syntax definition for configuring these features. Access to the manual documents is specified with the URL, http://yourserver.com/manual/index.html, where "yourserver.com" is the name of your HP 3000.

Hardware Requirements

The following are estimates for hardware resources required for an Apache installation.

32 MB of memory (64 MB recommended for machines with high traffic)
25 MB Disk Space (Apache directories and files + log files)
Additional disk space for your documents.

The 25 MB of disk space would be used approximately in the following way:

5 MB for Apache and its assorted static files
10 MB for the access log (about 100,000 requests)
10 MB for the error log (about 100,000 errors)

If you are using less than the recommended disk space for the log files, you may want to monitor their size. Each request or error message is about 100 bytes and both logs, but especially the access log, can grow quite large. Each request to the web server creates one entry in the access log.

Steps for Starting Apache

To start the Apache web server:

Prepare your system for network access.
Copy and edit the configuration file.
Edit the JHTTPD job stream file.
Start the HTTPD web server program.
Verify that the HTTPD web server is running.

Prepare Your HP 3000 for Network Access

Before your HP3000 can act as a web server, it must be available for network access via TCP/IP. In preparation, you should:

Configure TCP/IP on your system
Have a domain name associated with your system's IP address

Apache communicates on the network using the HTTP Hypertext Transfer Protocol which, in turn, uses TCP/IP. NS Transport (the TCP/IP transport subsystem) is configured on your HP 3000 using NMMGR. In NMMGR, configure your system's IP address and subnet mask in screen NEXTPORT.NI.Niname.PROTOCOL.IP. TCP should also be configured with the recommended values in the table below using screen NEXTPORT.GPROT.TCP. Information on the TCP/IP parameters is available in the NS3000/iX NMMGR Screens Reference Manual from http://docs.hp.com/mpeix.

TCP/IP Parameter	Recommended Value
Maximum number of connections	20,000
Retransmission Interval Lower Bound	1 second
Maximum time to wait for remote response	120 seconds
Initial Retransmission Interval	2 seconds
Maximum Retransmissions per Packet	6
Connection Assurance Interval	120 seconds
Maximum Connection Assurance Retransmissions	2

After completing your system's TCP/IP configuration, run :NETCONTROL START from the CI command line and verify that it ran successfully. Also verify that your system can respond over the network by running ping either from an HP 3000 or another system:


  :run ping.net.sys;info="15.99.200.390"

  64 byte(s) from $0F0DC0CF : icmp seq =    11, time =     2 ms
  64 byte(s) from $0F0DC0CF : icmp seq =    12, time =     3 ms
  64 byte(s) from $0F0DC0CF : icmp seq =    13, time =     2 ms
  < CONTROL-y >


  C:\>ping yourserver.com
  
  Pinging yourserver.com [15.99.200.390] with 32 bytes of data
  
  Reply from 15.99.200.390: bytes=32 time<10ms TTL=199
  Reply from 15.99.200.390: bytes=32 time<10ms TTL=199
  Reply from 15.99.200.390: bytes=32 time<10ms TTL=199

You will also want to get a domain name. This is a unique identifier such as "yourserver.com" which is used (instead of the IP address) to direct requests from a browser to your server. Request a domain name from the administrator of the Domain Name Server (DNS) on your network.

Configure Apache

Apache reads two global configuration files when it starts: httpd.conf and mime.types. These configuration files determine how Apache behaves. Earlier versions of Apache read two additional global configuration files: access.conf and srm.conf. These additional global configuration files can be still be used, but by default they are empty and their original content is now included in the httpd.conf file.

Edit your Configuration File

The mime.types file comes as mime.types.default and must be copied or renamed to mime.types. Similarly, the magic.default file must be copied or renamed. The httpd.conf file comes in two different versions. The httpd.conf.default file is for a UNIX-based platform installation. The httpd.conf.sample file was derived from the httpd.conf.default file with modifications for MPE. This is the file you should edit.


  shell> cd /APACHE/PUB/conf
  shell> cp mime.types.default mime.types
  shell> cp magic.default magic
  shell> cp httpd.conf.sample httpd.conf
  shell> vi httpd.conf

Uncomment and replace "yourserver.com" with your own server's name for the ServerAdmin and ServerName directives. You may also choose to make other changes. The Apache Server Project web site, http://www.apache.org/docs, has information about all of the configuration directives. All lines beginning with # are comments and are ignored by the HTTPD program file. Also note that the content of the configuration files is case sensitive. Changes to the global configuration files do not take effect until the web server is started (or stopped and restarted if it is already running).
The httpd.conf file could, alternatively, be edited with a PC editor by using SAMBA and setting up a share for the /APACHE/PUB/conf directory.
Verify the configuration file. It is a good idea to verify your configuration files before trying to start the web server. This verification is for syntax checking only.
```
  shell>/APACHE/PUB/HTTPD -t
```

Edit the JHTTPD Job Stream File

The JHTTPD Job Stream File is used to run the HTTPD web server program in standalone mode with your local timezone:


  !job jhttpd,www.apache,pub;outclass=,2
  !setvar TZ 'PST8PDT'
  !run HTTPD;info='-f /APACHE/PUB/conf/httpd.conf'
  !eoj

The timezone variable, TZ, should be set to your local timezone (for example, EST5EDT for Eastern Daylight Time, PST8PDT for Pacific Daylight Time, and MST7MDT for Mountain Daylight Time). For more information about setting the timezone value, enter "man timezone" in the POSIX shell to read the POSIX help file.

To preserve the access permissions (ACD) on the JHTTPD file, you can edit the file using the secure feature of EDITOR:


  :EDITOR
  /t JHTTPD
  /m ...
  /set secure
  /k
  JHTTPD,UNN
  JHTTPD ALREADY EXISTS - RESPOND YES TO PURGE OLD AND KEEP NEW
  PURGE OLD?yes
  /e

The JHTTPD file does not come with a password. If desired, the JOBSECURITY command can be used to provide password protection without adding your password to the file.

Start the HTTPD Web Server Program

The HTTPD web server program is started using the JHTTPD job file. Apache can be started from either the CI or the POSIX shell:


  :STREAM JHTTPD.PUB.APACHE
    or
  :xeq sh.hpbin.sys -L
  shell>callci "stream jhttpd.pub.apache"

Verify that Apache is Running

There are a number of ways to verify if the Apache web server is running or, if it is not, to isolate how far the startup process progressed.

After streaming the JHTTPD file, use :SHOWJOB to view the running job:


  JOBNUM  STATE IPRI JIN  JLIST    INTRODUCED  JOB NAME
  #J16    EXEC        10S LP       TUE 10:27A  JHTTPD,WWW.APACHE

Another method is to check server status using either ps from the POSIX shell or using :SHOWPROC at the CI. The parent process is the HTTPD process with the -f option.


 :SHOWPROC; job=jhttpd,www.apache
 D202    0:00.079        WAIT    J16     73   :RUN HTTPD;info='-f
   /APACHE/PUB/conf/httpd.conf'
 D238    1:25.371        WAIT    J16     97   (HTTPD.PUB.APACHE) -f
   /APACHE/PUB/conf/httpd.conf
 D202    0:00.066        WAIT    J16     78   (HTTPD.PUB.APACHE)
 D202    0:00.072        WAIT    J16     76   (HTTPD.PUB.APACHE)
 D202    0:00.069        WAIT    J16     93   (HTTPD.PUB.APACHE)
 D202    0:00.090        WAIT    J16     106  (HTTPD.PUB.APACHE)
 D202    0:00.050        WAIT    J16     99   (HTTPD.PUB.APACHE)
 D202    0:00.055        WAIT    J16     107  (HTTPD.PUB.APACHE)
 
 shell> ps -ef | grep HTTPD
        UID     PID    PPID C  STIME TTY    TIME COMMAND
 WWW.APACHE  720972  655457 0 Dec 31 ldev10 0:00 HTTPD.PUB.APACHE
 WWW.APACHE  589902  655457 0 Dec 31 ldev10 0:00 HTTPD.PUB.APACHE
 WWW.APACHE 3014749  655457 0 Dec 31 ldev10 0:00 HTTPD.PUB.APACHE
 WWW.APACHE  655457 5963849 0 Dec 31 ldev10 1:23 HTTPD.PUB.APACHE info=-f
 WWW.APACHE 4587619  655457 0 Dec 31 ldev10 0:00 HTTPD.PUB.APACHE
 WWW.APACHE  262250  655457 0 Dec 31 ldev10 0:00 HTTPD.PUB.APACHE
 WWW.APACHE 3407979  655457 0 Dec 31 ldev10 0:00 HTTPD.PUB.APACHE

After the HTTPD program is running, make sure you can also access files in the directory tree. Some pages to try are:

Your server's Home Page. This brings up the default home page. To modify this page, edit the /APACHE/PUB/htdocs/index.html file.
```
  http://yourserver.com
```
MGR.APACHE's Home Page. This is the default page for user MGR.APACHE. To modify this page, copy the sample file, then edit /APACHE/PUB/public_html/index.html.
```
  shell> cd /APACHE/PUB/public_html
  shell> cp index.html.sample index.html
  http://yourserver.com/~MGR.APACHE
```
The Apache on-line documentation manual
```
  http://yourserver.com/manual
```

If you are unsuccessful in starting the HTTPD program, you can get more information about the problem by trying one or more of these troubleshooting techniques:

Look at the output of the JHTTPD spoolfile
Check the messages in the /APACHE/PUB/logs/error_log file
Verify the syntax of the httpd.conf file. This catches many, but not all, syntax problems in the httpd.conf file
```
  :run HTTPD.PUB.APACHE:info="-t"
```
Try to telnet to Apache's port (port 80 if you have not modified the port directive set in the httpd.conf.sample file).

If you cannot telnet to Apache's port, then your problem is not with the web server. You are not yet reaching your HP 3000 box. A successful telnet connection should look something like,


  telnet yourserver.com 80
  Trying...
  Connected to yourserver.com.
  Escape character is '^]'.

Stopping Apache

Apache is stopped by aborting the Apache job from either the CI or the POSIX shell. Use SHOWJOB to view the Apache job:


  JOBNUM  STATE IPRI JIN  JLIST    INTRODUCED  JOB NAME
   #J16    EXEC      10S  LP       TUE 10:27A  JHTTPD,WWW.APACHE

  :ABORTJOB #J16 or
  :ABORTJOB JHTTPD,WWW.APACHE

Apache can also be stopped using :ABORTJOB from the POSIX shell


  :xeq sh.hpbin.sys -L
  shell>callci "abortjob #j16"
    or
  shell>callci "abortjob jhttp,www.apache"

Error Logging

Apache error logging is useful when trying to start Apache as well as for monitoring a running web server. Apache logs errors into a log file called error_log by default. This log file resides in the /APACHE/PUB/logs directory.

The number of messages logged in the error log is set by the LogLevel directive in the httpd.conf file. Possible values for LogLevel (by increasing significance) are debug, info, notice, warn, error, crit, alert, emerg. When a particular level is specified, messages from all other levels of higher significance are reported as well. For example, when LogLevel is "info", then messages with log levels of notice, warn and up to emerg are also posted.

By default, the level is set to warn. Using a level of at least crit is recommended.

Adding Documents

Add new documents by creating them under the document root, /APACHE/PUB/htdocs. Documents can also be added outside of the document root using the Alias directive in the httpd.conf file or by using symbolic links.

The web server children that handle user requests run as WWW.APACHE, the username specified in the JHTTPD file. For more security, user WWW.APACHE has been created with minimal capabilities. Make sure files are readable by WWW.APACHE and cgi scripts and programs are executable by WWW.APACHE. WWW.APACHE must also have traverse directory (TD) permission for all the directories in the path of the file that it is accessing. In the POSIX shell, traverse directory permission is shown as execute (x) permission for that directory.


  cd htdocs
  mkdir newdir
  chown MGR.APACHE:APACHE newdir
  chmod 750 newdir

One way to check if a file is accessible by Apache is to logon as WWW.APACHE and try to access the file.

Troubleshooting

For any kind of trouble with Apache, first look in the error log. Execute a tail command on the error_log from the POSIX shell to look at the last few entries. The last entry will be the most recent entry:


  shelliX> tail /APACHE/PUB/logs/error_log

For troubleshooting Apache at the source code level, the Apache program file can be run with the MPE debugger. It is best to run it with the -X (capital "X") option to prevent the parent Apache process from creating child processes:


  :run httpd.pub.apache;info="-X";debug

Unsupported Functionality

HP does not support Apache binaries built by individuals or organizations outside of HP.

HP also does not support the scripts and programs in the /APACHE/PUB/bin directory. This is contributed software from the Apache Software Foundation and is provided for example only.

Performance

For best performance, files returned to the user should be in bytestream format. For example, .html, .htm, .shtml, .shtm, .txt, .gif, .jpeg, and .jpg files, should be in bytestream format instead of in MPE-type format. Bytestream files are more compatible with Apache and with other POSIX applications than are MPE-type files. If you have a web page that calls many images which are not in bytestream format (BA), you could have noticeable performance degradation.

If any of your files under the document root (htdocs) are either MPE fixed ascii (FA), MPE variable ascii (VA), or MPE variable binary (VB) files, you should consider converting them to bytestream files using the "tobyte" utility. Program files (fixed binary (FB) files with an NMPROG filecode) should never be converted.

A file's filetype can be determined using either the POSIX file command or the CI listfile command:


  shell/iX> file index*.html
  index.html:   MPE/iX 256-byte variable length binary (filecode: 0)
  index1.html:  MPE/iX 80-byte fixed length ascii (filecode:0)

  shell/iX>callci listfile ./index.html,2
  PATH= /APACHE/PUB/htdocs/CODE
 
  CODE  ------------LOGICAL RECORD-----------  ----SPACE----  FILENAME
          SIZE  TYP        EOF      LIMIT R/B  SECTORS #X MX

          128W  VB          19     204800   1       32  1  8  index.html
           80B  FA          54     204800   1       32  1  8  index1.html

To convert an ASCII-type file (.htm*, .shtm*, or .txt), use the tobyte utility with the -at option. If it is a binary-type file (such as .jpeg, .jpg, or .gif), do not use the -at option:


 tobyte -at /APACHE/PUB/htdocs/index.html /APACHE/PUB/htdocs/newindex.html

For more information on the "tobyte" utility, use the POSIX help facility (i.e. man tobyte).

If your Apache web server seems slow in responding, you might try running the Apache job stream file, JHTTPD, in the C queue instead of in the default D queue. The changes shown below allow Apache to run in the C queue while keeping the default execution level for jobs in the D queue. The jobpri command can be executed on the console or in a systart file.


  !job JHTTPD,www.apache;pri=cs;outclass=,2
  
  jobpri cs

Additional Documentation

Much of the public information available on Apache can be used for administrating Apache on MPE/iX. This especially applies to the description and usage of the over 128 different Apache configuration directives.

Sources for additional information include

The Apache on-line manual pages included as part of MPE FOS at http://yourserver.com/manual/index.html
The Apache Software Foundation's on-line documentation at http://www.apache.org/docs
Apache books, published by various publishers, such as O'Reilly and Associates, Inc. and IDG Books Worldwide, Inc.

For downloadable software to enhance your web site (perl, sendmail, python, etc.), visit MPE's external Jazz web server at http://jazz.external.hp.com.

Feature Set

Chapter 10 HP WebWise MPE/iX Secure Web Server