News
Abstract
IBM HTTP Server Upgrading to Apache 2.4
Content
Introduction
IBM HTTP Server is updated to be based on Apache 2.4 in IBM i 7.2 released in May, 2014. Comparing to Apache 2.2 in IBM i 7.1 and i 6.1, there are many significant improvements, configuration changes and new features.
This article describes the major points when migrate to Apache 2.4 and some new features in Apache 2.4.
Upgrading to Apache 2.4
Below are some key areas that may require users to pay attention or take actions in order to let your HTTP servers behavior same as before after moving to Apache 2.4 on IBM i 7.2.
1. Configuration-related changes
Configuration-related changes include directive remove, syntax/default value change, module rename/refactor etc that may require users to update httpd.conf file if applicable.
Module mod_deflate specifies compression and decompression functions using filters, MIME types, environment variables, and HTTP responses. Compressed output is transferred to requesting client browsers at a higher rate of speed than output that is not compressed. Compression and decompression is implemented by the DEFLATE filter, located in module mod_deflate. The below line is required in your HTTP server configuration file when you want to add the DEFLATE input/output filter or using any directives from the mod_deflate. (This requirement also applies for older releases IBM i 6.1 and 7.1 ) LoadModule deflate_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM On IBM i 6.1 and 7.1 which are based on Apache 2.2, if user only sets the DEFLATE input/output filter like below and does not specify any directives of mod_deflate and does not have the required LoadModule deflate_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM, the HTTP server can be started successfully but the DEFLATE input/output filter does not work at all due to can't find the DEFLATE filter which is provided by the module mod_deflate. SetOutputFilter DEFLATE AddOutputFilterByType DEFLATE text/javascript User may find below error in the error log: [error] ZSRV_MSG0655: an unknown filter was not added: DEFLATE The above example is used to compress all JavaScript response data before sending to client. If user does not add the LoadModule directive, the JavaScript response data will not be compressed at all. If users do not notice the error in error log or do not check the request/response data, they might thought the DEFLATE input/output filter worked as expect which actually not. On IBM i 7.2 and i 7.3 which are based on Apache 2.4, there is a pre-check added at the server startup phase to check whether the module which provides the specific filter is loaded. If the module is not loaded via the LoadModule directive, the HTTP server will fails to start with errors similar like below in job log: HTP8989 Diagnostic 40 08/12/16 14:12:48.065030 QZSRAPR QHTTPSVR *STMT QZSRCORE QHTTPSVR *STMT
This pre-check ensures user to fix the configuration issue to load the required module and get input/output filter to work as expect. If users find HTTP server fails to start when moving to IBM i 7.2 or i 7.3 with above error in job log, please add the LoadModule directive to your httpd.conf to fix the problem and restart your HTTP server.
|
2. Access control changes
Before IBM i 7.2, access control that is based on client host name, IP address, and other characteristics of client requests was done with the directives Order,
Allow, Deny, and Satisfy. In 7.2, such access control is done in the same way as other authorization checks, by using the new module mod_authz_host and mod_authz_core. The old access control idioms should be replaced by the new authentication mechanisms, although for compatibility with old configurations, the new module mod_access_compat is provided and loaded by default.
We suggest user move to use new access control directives especially for new created HTTP Servers. To prevent from getting unexpected result, Old and new access control directives are not suggested to be used together in one container.
Here are some examples of old and new ways to do the same access control:
Here are some examples of old and new ways to do the same access control:
Examples |
Old configuration |
New configuration |
Deny all requests |
Order deny,allow Deny from all |
Require all denied |
Allow all requests |
Order allow,deny Allow from all |
Require all granted |
All hosts in the example.org domain are allowed access and all other hosts are denied access. |
Order deny,allow Deny from all Allow from example.org |
Require host example.org |
Only allow users who pass the IBM i user profile authentication to access directory /www/webserver/auth | <Directory /www/webserver/auth> AuthName "auth" AuthType Basic PasswdFile %%SYSTEM%% UserID %%CLIENT%% Require valid-user order allow,deny allow from all </Directory> |
<Directory /www/webserver/auth> AuthName "auth" AuthType Basic PasswdFile %%SYSTEM%% UserID %%CLIENT%% Require valid-user </Directory> |
Besides the Require directive, the new core authorization module mod_authz_core provides some authorization container directives <RequireAll>, <RequireAny> and <RequireNone> which may be combined with each other and with the Require directive to express complex authorization logic.
In below example, user must either be the superadmin user, or belong to the admins group but must not belong to the temps group can access the resource.
<Directory /www/webserver/htdocs/mydocs> <RequireAll> <RequireAny> Require user superadmin <RequireAll> Require group admins </RequireAll> </RequireAny> <RequireNone> Require group temps </RequireNone> </RequireAll> </Directory> |
In configurations where both authentication and access control were meaningfully combined, the access control directives should be migrated. This example allows requests meeting both criteria:
Old configuration:
Order allow,deny Deny from all # Satisfy ALL is the default Satisfy ALL Allow from 127.0.0.1 AuthType Basic PasswdFile %%SYSTEM%% AuthName secure Require valid-user
New configuration:
AuthType Basic PasswdFile %%SYSTEM%% AuthName secure <RequireAll> Require valid-user Require ip 127.0.0.1 </RequireAll>
In configurations where both authentication and access control were meaningfully combined, the access control directives should be migrated. This example allows requests meeting either criteria:
Old configuration:
Order allow,deny Deny from all Satisfy any Allow from 127.0.0.1 AuthType Basic PasswdFile %%SYSTEM%% AuthName secure Require valid-user
New configuration:
AuthType Basic PasswdFile %%SYSTEM%% AuthName secure # Implicitly <RequireAny> Require valid-user Require ip 127.0.0.1
3. Plug-in modules
Due to the API changes in Apache 2.4, all HTTP Server plug-in modules are required to be recompiled against new Apache 2.4 runtime service programs on IBM i 7.2. Some modules' code may also need to be modified if the changed APIs are used. All IBM provided plug-in modules have been updated to correctly work with new Apache 2.4 HTTP server on i 7.2, all other third party and user written plug-in modules are required to be updated and recompiled before being loaded.
Note: HTTP Server API header files updated for Apache 2.4 are still in /QIBM/ProdData/HTTPA/include
WebSphere Application Server plug-in updates
On i 7.2, WebSphere Application Server plug-in is updated to QSVTAP24.SRVPGM. The WebSphere Application Server plug-in configuration directive in httpd.conf need to be updated to point the correct plug-in.
From:
LoadModule was_ap20_module /QSYS.LIB/QWAS8.x.LIB/QSVTAP22.SRVPGM
or
LoadModule was_ap20_module /QSYS.LIB/QWAS8.x.LIB/QSVTAP22LF.SRVPGM
To:
LoadModule was_ap20_module /QSYS.LIB/QWAS8.x.LIB/QSVTAP24.SRVPGM
From:
LoadModule was_ap20_module /QSYS.LIB/QHTTPSVR.LIB/QSVTAP22.SRVPGM
or
LoadModule was_ap20_module /QSYS.LIB/QHTTPSVR.LIB/QSVTAP22LF.SRVPGM
To:
LoadModule was_ap20_module /QSYS.LIB/QHTTPSVR.LIB/QSVTAP24.SRVPGM
Module Enhancements
Apache 2.4 has some updates and enhancements to existing Apache 2.2 modules. Below are some major enhancements in our HTTP server for IBM i 7.2.
Core module
The LogLevel directive can now be configured per module and per directory. For example, # log level is warn for SSL module and information for all other modules LogLevel info ibm_ssl_module:warn # log level is debug only for this directory <Directory "/www/apache/htdocs/app"> LogLevel debug </Directory>
New directives <If>, <ElseIf>, and <Else> sections can be used to set the configuration based on per-request criteria. For example, <If "-R '10.1.0.0/16'"> Redirect permanent / http://www.website1.com/ </If> <ElseIf "-R '10.0.0.0/8'"> Redirect permanent / http://www.website2.com/ </ElseIf> <Else> Redirect permanent / http://www.website3.com/ </Else>
A new expression parser allows to specify complex conditions using a common syntax in directives like SetEnvIfExpr, RewriteCond, Header, <If>, and others.
It is now possible to specify KeepAliveTimeout in milliseconds. For example, KeepAliveTimeout 5800ms
Specify directive AddServerHeader off to remove the Server header from the response if you does not want to expose the Server header to user.
The new AllowOverrideList directive allows more fine grained control which directives are allowed in .htaccess files. For example, # Only the Redirect and RedirectMatch directives are allowed. All others will cause an internal server error. AllowOverride None AllowOverrideList Redirect RedirectMatch
It is now possible to use new Define directive to define variables in the configuration, allowing a clearer representation if the same value is used at many places in the configuration. Use directive UnDefine to undo the effect of a Define. For example, <IfDefine TEST> Undefine SSL Define servername test.example.com </IfDefine> <IfDefine !TEST> Define SSL Define servername www.example.com </IfDefine>
With previous Apache 2.2 HTTP Server, LogFormat directive can be used to set log format for access log, but it's not allowed to change the format of error log. With new ErrorLogFormat directive in Apache 2.4, user can specify what supplementary information is logged in the error log in addition to the actual log message. For example, ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M" |
mod_proxy
|
mod_proxy_balancer
|
mod_cache
|
Support for the 'onerror' attribute within an 'include' element, allowing an error document to be served on error instead of the default error string.
mod_cgi, mod_include, ...
Translation of headers to environment variables is more strict than before to mitigate some possible cross-site-scripting attacks via header injection. Headers containing invalid characters (including underscores) are now silently dropped. Environment Variables in Apache has some pointers on how to work around broken legacy clients which require such headers. (This affects all modules which use these environment variables.)
mod_rewrite
|
mod_ibm_ssl
# Remove SSL_RSA_WITH_RC4_128_MD5 for all supported protocols SSLCipherSpec ALL -SSL_RSA_WITH_RC4_128_MD5 # Remove TLS_RSA_WITH_AES_128_CBC_SHA and add short name 3A for TLS1.1 SSLCipherSpec TLSV1.1 -TLS_RSA_WITH_AES_128_CBC_SHA +3A
Select ECDSA key via DCM GUI to use ECDHE ECDSA ciphers:
For example, user can access below two different HTTPS website by using their own certificate separately.
|
New modules
There are some new modules with useful functions in Apache 2.4, below are some basic introduction to some key new modules that currently supported in HTTP server on IBM i 7.2. For more detail information about those modules, refer to IBM i 7.2 IBM Documentation and Apache website.
mod_remoteip
This module is used to treat the user agent which initiated the request as the originating user agent as identified by HTTP Server for the purposes of authorization and logging, even where that user agent is behind a load balancer, front end server, or proxy server.
This module overrides the client IP address for the connection with the user agent IP address reported in the request header configured with the RemoteIPHeader directive.
Once replaced as instructed, this overridden user agent IP address is then used for the mod_authz_host Require ip feature, is recorded by mod_log_config and core %a format strings. The underlying client IP of the connection is available in the %{c}a format string.
mod_buffer
This module provides the ability to buffer the input and output filter stacks. Under certain circumstances, content generators might create content in small chunks. In order to promote memory reuse, in memory chunks are always 8k in size, regardless of the size of the chunk itself. When many small chunks are generated by a request, this can create a large memory footprint while the request is being processed, and an unnecessarily large amount of data on the wire. The addition of a buffer collapses the response into the fewest chunks possible.
When HTTP Server is used in front of an expensive content generator, buffering the response may allow the backend to complete processing and release resources sooner, depending on how the backend is designed.
The buffer filter may be added to either the input or the output filter stacks, as appropriate, using the SetInputFilter, SetOutputFilter, AddOutputFilter or AddOutputFilterByType directives. For example: Using buffer with mod_include
AddOutputFilterByType INCLUDES;BUFFER text/html
mod_data
This module provides the ability to convert a response into an RFC2397 data URL.
Data URLs can be embedded inline within web pages using something like the mod_include module, to remove the need for clients to make separate connections to fetch what may potentially be many small images. Data URLs may also be included into pages generated by scripting languages such as PHP.
An example of a data URL
data:image/gif;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAwAAAC8IyPqcvt3wCcDkiLc7C0qwyGHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFzByTB10QgxOR0TqBQejhRNzOfkVJ+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSpa/TPg7JpJHxyendzWTBfX0cxOnKPjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJlZeGl9i2icVqaNVailT6F5iJ90m6mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uisF81M1OIcR7lEewwcLp7tuNNkM3uNna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PHhhx4dbgYKAAA7
The filter takes no parameters, and can be added to the filter stack using the SetOutputFilter directive, or any of the directives supported by the mod_filter module.
For example:
<Location /data/images>
SetOutputFilter DATA
</Location>
mod_ratelimit
This module provides a filter named RATE_LIMIT to limit client bandwidth. The connection speed to be simulated is specified, in KiB/s, using the environment variable rate-limit.
For example:
<Location /downloads>
SetOutputFilter RATE_LIMIT
SetEnv rate-limit 400
</Location>
mod_request
This module provides filters to handle and make available HTTP request bodies
Under normal circumstances, request handlers such as the default handler for static files will discard the request body when it is not needed by the request handler.
When directive KeptBodySize has a value greater than zero, request handlers that would otherwise discard request bodies will instead set the request body aside for use by filters up to the maximum size specified.
This feature makes it possible to break up complex web pages and web applications into small individual components, and combine the components and the surrounding web page structure together using mod_include. The components can take the form of CGI programs, scripted languages, or URLs reverse proxied into the URL space from another server using mod_proxy.
If the request size sent by the client exceeds the maximum size allocated by the KeptBodySize directive, the server will return 413 Request Entity Too Large.
mod_reflector
This module provides Reflection of a request body as a response via the output filter stack.
This module allows request bodies to be reflected back to the client, in the process passing the request through the output filter stack. A suitably configured chain of filters can be used to transform the request into a response. This module can be used to turn an output filter into an HTTP service.
For example,
Pass the request body through the DEFLATE filter to compress the body. This request requires a Content-Encoding request header containing "gzip" for the filter to return compressed data.
<Location /compress>
SetHandler reflector
SetOutputFilter DEFLATE
</Location>
mod_reqtimeout
This module sets timeout and minimum data rate for receiving requests.
The new RequestReadTimeout directive can set various timeouts for receiving the request headers and the request body from the client. If the client fails to send headers or body within the configured time, a 408 REQUEST timeout error is sent.
Examples
1. Allow 10 seconds to receive the request including the headers and 30 seconds for receiving the request body: RequestReadTimeout header=10 body=30 2. Allow at least 10 seconds to receive the request body. If the client sends data, increase the timeout by 1 second for every 1000 bytes received, with no upper limit for the timeout (except for the limit given indirectly by LimitRequestBody): RequestReadTimeout body=10,MinRate=1000 3. Allow at least 10 seconds to receive the request including the headers. If the client sends data, increase the timeout by 1 second for every 500 bytes received. But do not allow more than 30 seconds for the request including the headers: RequestReadTimeout header=10-30,MinRate=500 4. Usually, a server should have both header and body timeouts configured. If a common configuration is used for http and https virtual hosts, the timeouts should not be set too low: RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500 |
mod_watchdog
This module provides infrastructure for other modules to periodically run tasks. It defines programmatic hooks for other modules to periodically run tasks.
These modules can register handlers for mod_watchdog hooks.
Full list of new modules
Below is a full list of new Apache 2.4 modules supported in HTTP server for i 7.2. For all modules that are not pre-loaded by HTTP server must be explicitly loaded by specifying LoadModule Module_identifier /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM in httpd.conf.
Module identifier |
Pre-load |
Module Description |
access_compat_module |
Yes |
Group authorizations based on host (name or IP address).It's a compatibility module with previous versions of Apache2.x |
authn_core_module |
Yes |
Core Authentication |
authz_core_module |
Yes |
Core Authorization |
buffer_module |
NO |
Support for request buffering |
cache_disk_module |
NO |
Rename of disk_cache_module in Apache 2.x |
data_module |
NO |
Convert response body into an RFC2397 data URL |
lbmethod_bybusyness_module |
NO |
Pending Request Counting load balancer scheduler algorithm for mod_proxy_balancer |
lbmethod_byrequests_module |
NO |
Request Counting load balancer scheduler algorithm for mod_proxy_balancer Note: This is the default load-balance method in Apache 2.x. |
lbmethod_bytraffic_module |
NO |
Weighted Traffic Counting load balancer scheduler algorithm for mod_proxy_balancer |
ratelimit_module |
NO |
Bandwidth Rate Limiting for Clients |
reflector_module |
Yes |
Reflect a request body as a response via the output filter stack. |
remoteip_module |
Yes |
Replaces the original client IP address for the connection with the useragent IP address list presented by a proxies or a load balancer via the request headers. |
reqtimeout_module |
NO |
Set timeout and minimum data rate for receiving requests |
request_module |
Yes |
Filters to handle and make available HTTP request bodies |
slotmem_plain_module |
NO |
Slot-based shared memory provider which provides for creation and access to a plain memory segment in which the data sets are organized in "slots" |
slotmem_shm_module |
Yes |
Slot-based shared memory provider which provides for creation and access to a shared memory segment in which the data sets are organized in "slots" |
watchdog_module |
Yes |
provides infrastructure for other modules to periodically run tasks |
New feature - HTTP server run in user created subsystem
The default subsystem and job queue for HTTP server jobs is QHTTPSVR and QHTTPSVR/QZHBHTTP. On i 7.2, HTTP Server can be configured to run in user created subsystem so that user can put one or more key HTTP servers run in another subsystem with own allocated memory pool when needed.
It's users' responsibilities to create the new subsystem, job queue (job description and routing data if needed) via a series CL commands and specify them via new directives HTTPSubsystemDesc, HTTPStartJobQueue, HTTPStartJobDesc and HTTPRoutingData in HTTP configuration file.
References
http://httpd.apache.org/docs/2.4/upgrading.html
http://httpd.apache.org/docs/2.4/new_features_2_4.html
http://httpd.apache.org/docs/2.4/developer/new_api_2_4.html
http://httpd.apache.org/docs/2.4/howto/access.html
http://httpd.apache.org/docs/2.4/mod/mod_authz_core.html
http://httpd.apache.org/docs/2.4/mod/
http://www-01.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzahg/ic-homepage.htm
https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/rzain/rzainsystemssl.htm
http://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol
Was this topic helpful?
Document Information
Modified date:
08 May 2022
UID
ibm11169788