Apache web server
The HTTPD web server is the Apache web server ported to run on z/OS. It runs in Unix Services, and behaves like a proper z/OS program, for example it can use z/OS userids and keyrings. It starts in seconds!
The configuration is easy, it is text driven (rather than XML), can imbed other configuration files, and can substitute variables.
I found the Apache documentation was very good, but the z/OS documentation was not as good. I prefer baby steps, taking the smallest system and adding functions, rather than configure everything and be disappointed when it fails to work first time.
- Extending HTTPD server on z/OS
- Configuring the config file
- Getting HTTPD server to work with TLS on z/OS
- Httpd server – what is configured?
I used the IBM HTTP Server – Powered by Apache Version 9 PDF document. The text below is an addition to the IBM documentation, not a replacement. I’m trying to fill the holes in the documentation.
The product comes pre-installed. Mine was in /usr/lpp/ihsa_zos/bin/httpd
You need a directory for your HTTPD instance.
You need the userid to run the server.
ADDUSER WEB2 NAME(‘COLWEB’) NOPASSWORD –
OMVS(AUTOUID ASSIZE(256000000) THREADS(512) –
CONNECT IBMUSER GROUP(COLWEB )
CONNECT WEB2 GROUP(COLWEB )
When you set up the userid, it is better to use OMVS(AUTOUID .. than to give a specific numeric id, similarly use OMVS(AUTOGID… for the group.
The userid needs OMVS, PROGRAM= /bin/sh, and a home directory.
Setup the system with environment file
The /usr/lpp/ihsa_zos/bin/envvars file allows you to set up an image wide environment file. You can rename /usr/lpp/ihsa_zos/bin/envvars-std to /usr/lpp/ihsa_zos/bin/envvars
I set up this file with
Create the instance
Follow the instructions in the documentation.
bin/install_ihs /u/mqweb3 8300
Note down the port you specified (8300) as you will need it when you try to connect to the server.
The documentation says switch to the instance directory and issue apachectl -v. This failed for me because the path and libpath were not set up. I set up the envvars file (above) and it worked.
When I ran it, it produced
test: /usr/lpp/ihsa_zos/bin/apachectl 49: FSUM7351 not found
[: /usr/lpp/ihsa_zos/bin/apachectl 74: FSUM7351 not found
[: /usr/lpp/ihsa_zos/bin/apachectl 87: FSUM7351 not found
[: /usr/lpp/ihsa_zos/bin/apachectl 92: FSUM7351 not found
Server version: IBM_HTTP_Server/22.214.171.124 (Unix) (SMP/E, 64-bit)
Server built: Jun 10 2020 16:22:51
The FSUM7351 messages are OK. For example the apachectl script has
if test -f /usr/lpp/ihsa_zos/bin/envvars; then
This checks the file exists before invoking it.
The apachectl takes the following options, so you can display the configuration, or modify the start.
-D name : define a name for use in directives
-d directory : specify an initial ServerRoot
-f file : specify an alternate ServerConfigFile
-C “directive” : process directive before reading config files
-c “directive” : process directive after reading config files
-e level : show startup errors of level (see LogLevel)
-E file : log startup errors to file
-v : show version number
-V : show compile settings
-h : list available command line options (this page)
-l : list compiled in modules
-L : list available configuration directives
-t -D DUMP_VHOSTS : show parsed vhost settings
-t -D DUMP_RUN_CFG : show parsed run settings
-S : a synonym for -t -D DUMP_VHOSTS -D DUMP_RUN_CFG
-t -D DUMP_MODULES : show all loaded modules
-M : a synonym for -t -D DUMP_MODULES
-t -D DUMP_SSL_CONFIG: show parsed SSL vhost configurations
-t -D DUMP_SSL_CIPHERS: show all known SSL ciphers
-t -D DUMP_UNIFIED_CONFIG: show configuration with all includes merged
-t -D DUMP_INCLUDES: show all included configuration files
-t : run syntax check for config files
-T : start without DocumentRoot(s) check
-X : debug mode (only one worker, do not detach)
-t -DDUMP_CONFIG is very useful as it shows what you have configured after any <If…> and after variable substitution. I use this as a standalone command to see what’s configured.
Note:I had problems using //STDENV in the started task, so I had to use the envvars file.
Create the JCL procedure
See the documentation.
//HTTPCP PROC ACTION='start', // DIR='/usr/lpp/ihsa_zos', // CONF='/u/mqweb3/conf/httpd.conf' //*--------------------------------------------------------- //IHS EXEC PGM=BPXBATCH,REGION=0M, // PARM='SH &DIR/bin/apachectl -k &ACTION -f &CONF -DNO_DETACH ', // MEMLIMIT=1236M //STDOUT DD SYSOUT=H //STDERR DD SYSOUT=H // PEND
BPXBATCH needs REGION=0M, and at least MEMLIMIT=1236M
Define the STARTED task to RACF.
RDEFINE STARTED HTTPCP* STDATA(USER(WEBSRV)
SETROPTS RACLIST(STARTED ) REFRESH
Start the started task
You cannot just type P HTTPCP. In the syslog I had
CRIHS0001I IHS S0W1 is active. 83951827 0.0.0.0:8300 unspecified:-1.
Use jobname HTTPCP6 for console commands.
This means you have to issue P HTTPCP6 to stop it.
You can also use
To start and stop the server.
Note: When you run these commands it checks the syntax of the configuration file, and if there is a problem, then the command is not executed. I kept wondering why my HTTPD instance was not shutting down; it was because I had a configuration error, and so the stop request was being ignored.
If it starts (there are no helpful messages saying success) try connecting a web browser to it in my case
This gave me page with links to IBM sites. If you get here – you have done the first baby step. You cannot do much with the server.