Performing required z/OS system configurations

Before starting IBM® HTTP Server, there are required z/OS® system configurations that you must set up.

About this task

In order to run IBM HTTP Server, you must set the following z/OS system configurations:

Set the memlimit parameter.
Configure a mechanism for allowing access to low ports.
Required System Authorization Facility (SAF) configurations.
Setting environment variable * _BPX_JOBNAME (optional).

Procedure

Configure the System Management Facilities (SMF).
The IBM HTTP Server user ID must have read authority to the BPX.SMF facility. For more information, see Configuring IBM HTTP Server for SMF recording.
Starting in version 8.5.5.4, if compression offload is available on the zEnterprise® Data Compression (zEDC) system, and the IBM HTTP Server uses HTTP compression, load the mod_deflate_z module instead of the traditional mod_deflate.so module.

Note: In future releases, this exploitation is to be incorporated into the mod_deflate.so module.
Verify the MEMLIMIT parameter.
The MEMLIMIT parameter controls the amount of virtual memory higher than 2 gigabytes for a particular address space. The default setting for the MEMLIMIT parameter is 2 GB in z/OS V1R10 and later and is sufficient for the default server configuration. However, if the ThreadsPerChild directive is increased from the default of 25, increase the MEMLIMIT parameter by the same factor.
- The MEMLIMIT parameter can be set in the OMVS segment of the user ID that is used to run the server:
```
ALTUSER WWWSERV OMVS(MEMLIMIT(2048M))
```
- The MEMLIMIT parameter can also be set in the SMFPRMxx parmlib member. Set the SMFPRMxx parmlib member to establish the system-wide MEMLIMIT parameter default.
For a complete description of how to set the MEMLIMIT parameter, see Limiting the use of memory objects in z/OS V1R10.0 MVS Programming: Extended Addressability Guide (SA22-7614-06).

IBM HTTP Server requires a minimum of 5.4 MB of 64-bit virtual memory per thread. The minimum recommended MEMLIMIT setting for proper IBM HTTP Server operation is (ThreadsPerChild + 3) × 12 MB.
Configure a mechanism for allowing access to low ports.
The Web server user ID must have access to the TCP ports on which it will handle client connections. If port values less than 1024 are used, such as Web server ports 80 and 443, special configuration is required to allow the Web server to bind to the port.
You can use one of the following mechanisms to allow access to low ports:
- Set the PORT directive in the TCP/IP configuration.
- Disable RESTRICTLOWPORTS in the TCP/IP configuration.
- Code the Web server job name on a PORT statement in the TCP/IP configuration.
- Code a wildcard for the job name on a PORT statement in the TCP/IP configuration.
- Code SAF and a safname value on the PORT statement in the TCP/IP configuration, and permit the Web server user ID read access to the SAF FACILITY class profile EZB.PORTACCESS.sysname.stackname.safname.
For more information on configuration methods for allowing access to low ports, refer to the sections Port access control and Setting up reserved port number definitions in PROFILE.TCPIP in z/OS Communications Server IP Configuration Guide (SC31-8775). You can link to this document from the z/OS Internet Library.

For an explanation of how Unix System Services jobnames (such as those for IBM HTTP Server instances) are determined, refer to the section Generating jobnames for OMVS address spaces in z/OS UNIX System Services Planning (GA22-7800). Link to this document from the z/OS Internet Library.
Required System Authorization Facility (SAF) configurations.
- Create a user ID and group for IBM HTTP Server.
  You can use a new or existing user ID. It must have an OMVS segment and the UID cannot be zero. The following example contains RACF® commands to create a new user and group. For requirements, standard requirements terminology should be used, as suggested by RFC 2119 (https://www.ietf.org/rfc/rfc2119.txt). You can use a new or existing user ID. It must have an OMVS segment and the UTD must not be zero.
```
Password example

ADDGROUP WWWGROUP OMVS(GID(999))
ADDUSER  WWWSERV  DFLTGRP(WWWGROUP) OMVS(UID(999)) PASSWORD(password)
```
```
Password phrase example

ADDGROUP WWWGROUP OMVS(GID(999))
ADDUSER  WWWSERV  DFLTGRP(WWWGROUP) OMVS(UID(999)) PHRASE('my0users@99#701_workgroup')
```
  The security administrator should define the password for the Web server user ID, instead of allowing it to default, to prevent an unauthorized user from being able to log in with that user ID. The ALTUSER command can be used to modify the password of an existing user ID.
  Note: If you use a JCL cataloged procedure to start an IBM HTTP Server instance, create a SAF STARTED profile to assign the server user ID and group ID to the server started task. For example, to use a cataloged procedure named WEBSRV1:
```
RDEFINE STARTED WEBSRV1.* STDATA(USER(WWWSERV) GROUP(WWWGROUP) TRACE(YES))
```
- Set program control for required MVS data sets.
  Ensure that program control is turned on for the following MVS data sets. For hlq, enter the high level qualifier for your system installation, for example: SYS1.LINKLIB.
  - hlq.LINKLIB
  - hlq.SCEERUN
  - hlq.SCEERUN2
  - hlq.SCLBDLL
  The following example shows how to turn on program control using RACF commands. If you are using another security product, refer to that product's documentation for instructions. If you are turning on program control for the first time, you should use RDEFINE statements instead of RALTER statements:
```
RALTER PROGRAM * ADDMEM('hlq.LINKLIB'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM('hlq.SCEERUN'//NOPADCHK) UACC(READ)
RALTER PROGRAM * ADDMEM('hlq.SCLBDLL') UACC(READ)
SETROPTS WHEN(PROGRAM) REFRESH
```
  In this example, an asterisk (*) is used to specify all programs in the data set.
- Set program control for HFS files.
  The SMP/E installation logic enables the program control bit for the provided libraries and executable files that need it. If you install custom plug-in modules, use the extattr command to enable the APF and Program Control flags. For example:
```
# extattr +ap /opt/IBM/HTTPServer/modules/mod_jauth.so
```
  In this example, substitute the IBM HTTP Server installation location for /opt/IBM/HTTPServer/. (You can build custom plug-in modules using the apxs script that is provided.)
- Set program control for z/OS System SSL.
  If you set up your IBM HTTP Server to provide secure communications over the Internet, IBM HTTP Server uses z/OS System Secure Sockets Layer (SSL) to establish the secure connections. Before IBM HTTP Server can use System SSL, you must:
  - Add the System SSL load library (hlq.SIEALNKE) to the system link list or to the STEPLIB DD concatenation in the HTTP Server cataloged procedure
  - Set program control hlq.SIEALNKE in RACF.
  The variable hlq is the high level qualifier for your system installation, for example: SYS1.SIEALNKE.
  To turn on program control using RACF, issue the following command:
```
RALTER PROGRAM * ADDMEM('hlq.SIEALNKE'//NOPADCHK) UACC(READ)
SETROPTS WHEN(PROGRAM) REFRESH
```
  If you are turning on program control for the first time, use the RDEFINE statements instead of the RALTER statements. If you are using another security product, refer to that product's documentation for instructions.
- Access to SAF key rings.
  The SSL and LDAP authentication support can optionally use certificates stored in SAF key rings. This requires that the Web server user ID have certain SAF permissions. Specifically, the Web server user ID must be permitted to the IRR.DIGTCERT.LISTRING facility in order to use key rings. Here are the general steps required:
  1. Define the IRR.DIGTCERT.LIST and IRR.DIGTCERT.LISTRING resources with universal access of None.
  2. Permit the Web server user ID read access to the IRR.DIGTCERT.LIST and IRR.DIGTCERT.LISTRING resources in the FACILITY class.
  3. Activate the FACILITY general resource class.
  4. Refresh the FACILITY general resource class.
  The following commands are RACF commands. Replace WWWSERV with the actual user ID with which IBM HTTP Server is started.
```
RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
PE IRR.DIGTCERT.LIST CLASS(FACILITY) ID(WWWSERV) ACCESS(READ)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PE IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(WWWSERV) ACCESS(READ)
SETR CLASSACT(FACILITY)
SETR RACLIST(FACILITY) REFRESH
```
  For a complete guide to RACF commands, refer to z/OS Security Server RACF Security Administrator's Guide (SA22-7683). You can link to this document from the z/OS Internet Library.
- Permitting user IDs to CSFSERV for hardware encryption:
  Integrated Cryptographic Services Facility (ICSF) is the software interface to the cryptographic hardware. If you plan to run IBM HTTP Server with cryptographic hardware capability, you can restrict the use of ICSF services. To restrict the use of ICSF services, you can permit user IDs to certain profiles in the CSFSERV general resource class. CSFSERV controls the use of ICSF software. If you have defined your IBM HTTP Server to execute with a nonzero user ID, you can give the nonzero user ID READ access to CSFSERV. If you are using a security product other than RACF, refer to that product's documentation for instructions.
  
  If you want to restrict the use of ICSF services, issue RACF commands similar to the commands in the following examples. If you have applications other than IBM HTTP Server that are using ICSF, you must customize the examples. Otherwise, the other applications will no longer have access to ICSF services.
  
  Important: Modern Transport Layer Security (TLS) support requires the CSFSERV general resource class to be configured and accessible by the IBM HTTP Server user ID. This configuration is necessary because random number generation by the server generates CSFRNG calls during normal operation.
  The following example shows how to permit the WWWSERV ID and the PUBLIC ID access to profiles in CSFSERV.
```
SETROPTS RACLIST(CSFSERV) GENERIC(CSFSERV)
RDEFINE CSFSERV CSF* UACC(NONE)
PERMIT CSF%%C CLASS(CSFSERV) ID(WWWSERV PUBLIC) ACCESS(READ)
PERMIT CSFPK% CLASS(CSFSERV) ID(WWWSERV PUBLIC) ACCESS(READ)
PERMIT CSFCK% CLASS(CSFSERV) ID(WWWSERV PUBLIC) ACCESS(READ)
SETROPTS CLASSACT(CSFSERV)
SETROPTS RACLIST(CSFSERV) GENERIC(CSFSERV) REFRESH
```
  The following example shows how to give user IDs and the WWWSERV ID access to profiles in CSFSERV.
```
SETROPTS RACLIST(CSFSERV) GENERIC(CSFSERV)
RDEFINE CSFSERV CSF%%C UACC(READ)
RDEFINE CSFSERV CSFPK% UACC(READ)
RDEFINE CSFSERV CSFCK% UACC(READ)
SETROPTS CLASSACT(CSFSERV)
SETROPTS RACLIST(CSFSERV) GENERIC(CSFSERV) REFRESH
```
- Using cryptographic hardware for key storage (optional):
  To perform key storage on cryptographic devices refer to the section Integrated Cryptographic Service Facility (ICSF) Considerations in z/OS Security Server RACF Security Administrator's Guide (SA22-7683).
  
  For information on ICSF options refer to the section Using Hardware Cryptographic Features with System SSL in z/OS Cryptographic Services System Secure Sockets Layer (SSL) Programming (SC24-5901).
  
  You can link to both of these documents from the z/OS Internet Library.
Setting environment variable * _BPX_JOBNAME (optional):
IBM HTTP Server provides the file <installroot>/bin/envvars for setting environment variables for the httpd processes. You can set the environmental variable * _BPX_JOBNAME to give the server a distinct jobname. This allows you to:
- See the server in MVS operator commands and System Display and Search Facility (SDSF).
- Categorize the server in workload management (WLM) to give web traffic adequate priority.
- Use syslogd isolation for the server.
- Use PORT statements in the TCP/IP configuration that select by job name.
A typical setting is: export _BPX_JOBNAME=HTTPD. The default is to append an incrementing integer to your jobname, such as HTTPD1, HTTPD2, HTTPD3. For more information refer to the section Generating jobnames for OMVS address spaces in z/OS UNIX System Services Planning (GA22-7800). Link to this document from the z/OS Internet Library.
If you use the _BPX_JOBNAME variable to set the jobname, the user ID which you use to run the server must have read access to the SAF FACILITY profile BPX.JOBNAME. For example:
```
RDEFINE FACILITY BPX.JOBNAME  UACC(NONE)
SETROPTS RACLIST(FACILITY) REFRESH 
PERMIT BPX.JOBNAME CLASS(FACILITY) ACCESS(READ) ID(WWWSERV) 
SETROPTS RACLIST(FACILITY) REFRESH 
RLIST FACILITY BPX.JOBNAME ALL
```
For more information refer to the section Setting up the BPX.* FACILITY class profiles in z/OS UNIX System Services Planning (GA22-7800). Link to this document from the z/OS Internet Library.