Issue
After an upgrade to IBM i 7.2 or 7.3, the ZENDPHP7 (or ZENDSVR6 for earlier versions of Zend Server) Apache instance will not start. This is due to an incompatibility between Apache 2.4 and Apache 2.2.
Environment
Zend Server for IBM i version 7.0.0 or higher, running on IBM i recently upgraded to version 7.2 or higher from 7.1 or earlier.
Resolution
The upgrade from IBM i 7.1 or earlier to IBM i 7.2 or later includes an upgrade of Apache from version 2.2 to 2.4. In 2.2, the Include directive is considered an optional include. The included file does not have to exist. In 2.4, the Include
directive is changed to mean the included file must exist, and the new IncludeOptional
directive acts the way the Include directive did in prior versions.
For new installations into IBM i 7.2, the installer can determine that the IncludeOptional directive is needed in the ZENDPHP7 (or ZENDSVR6) Apache configuration. However, when an existing configuration already exists during the upgrade to 7.2, there is no opportunity for the Zend installer to make this adjustment, and it must be done manually.
This procedure requires changing Apache configuration files. As with all configuration file changes, it is a good idea to back up the files before changing them. Here are the required changes (in each line, you are only changing the Include
directive to IncludeOptional
):
For Zend Server 9 and higher, change these two files:
Change this:
Include /usr/local/zendphp7/etc/sites.d/globals-*.conf
Include /usr/local/zendphp7/etc/sites.d/vhost_*.conf
To this:
IncludeOptional /usr/local/zendphp7/etc/sites.d/globals-*.conf
IncludeOptional /usr/local/zendphp7/etc/sites.d/vhost_*.conf
Change this:
Include /usr/local/zendphp7/etc/sites.d/http/__default__/0/*.conf
To this:
IncludeOptional /usr/local/zendphp7/etc/sites.d/http/__default__/0/*.conf
In each line, you are only changing the Include
directive to IncludeOptional
.
For Zend Server 6 through 8.5, change these two files:
Change this:
Include /usr/local/zendsvr6/etc/sites.d/globals-*.conf
Include /usr/local/zendsvr6/etc/sites.d/vhost_*.conf
To this:
IncludeOptional /usr/local/zendsvr6/etc/sites.d/globals-*.conf
IncludeOptional /usr/local/zendsvr6/etc/sites.d/vhost_*.conf
Change this:
Include /usr/local/zendsvr6/etc/sites.d/http/__default__/0/*.conf
To this:
IncludeOptional /usr/local/zendsvr6/etc/sites.d/http/__default__/0/*.conf
In each line, you are only changing the Include directive to IncludeOptional.
Virtual Host Definitions
If you have defined Virtual Hosts in the Applications section of the Zend Server User Interface, you should check to verify that the Virtual Host definitions include files are updated to show IncludeOptional
. If Apache will not start, you cannot edit these in the Zend Server UI, so you will need to update the files manually. You will find these files in the /usr/local/zendphp7/etc/sites.d (or /usr/local/zendsvr6/etc/sites.d for Zend Server 6 - 8.5) directory. Once you restart Apache, you can modify the Virtual Host templates to use IncludeOptional
, so that the Virtual Hosts will not be shown as modified.
Save the changes. It should now be possible to start Apache. If Apache still will not start, read on.
Mixed Option Types
There was another change for Apache 2.4 for the Options
directive where you can not have an option without a + or - mixed with one that does. This used to be allowed in Apache 2.2. So, in a configuration file, you might see an Options
directive like this:
In this example, the first argument +Indexes
has the plus sign, but the second argument has no sign at all. You can fix this by simply putting the plus sign on the second argument:
We see this example sometimes in Deployed Applications and Deployed Virtual Hosts. In some versions, the Deployment component would write the FollowSymLinks
argument without the plus sign. This has been changed in later versions, but older Deployed Applications and Virtual Hosts may still have the unsigned argument.
As mentioned above, you can find Deployed Virtual Host configurations in the /usr/local/zendphp7/etc/sites.d (or /usr/local/zendsvr6/etc/sites.d for Zend Server 6 - 8.5) directory. You can find Deployed Application configurations in directories named using this convention:
Where $zendxxxn
will be either zendphp7
for versions 9 and higher, or zendsvr6
for versions 6 to 8.5. $vhname
will be the name of the Virtual Host the app is deployed to (__default__
if deployed to the default host), and the port number assigned to the virtual host (this will be zero for the default virtual host).
An application deployed to the default virtual host in Zend Server 9 would be found here:
An application deployed to a virtual host named MySSLHost.com at port 443 in Zend Server 8.5 would be found here:
One app that is very commonly deployed on IBM i is the Samples app that includes XML Toolkit examples. For Zend Server 9, the full path to the samples config file would be something like this:
You do need to check all of your Deployed configuration files. One way you can get a complete list is to run this command in a PASE shell:
For Zend Server 9 or higher:
For Zend Server 6 to 8.5:
Alternate Resolution
Another way to resolve the Include issue is to create dummy files so that there is always something for the Include to find. These files do not need to have any directives in them. They can be totally blank, but it might be good to put some explanatory comments in them describing why they are there.
For example, you could create these files:
If you need to add some files for Include
directives found in Virtual Hosts, you could do that as well.
This is a less preferable solution, as it creates a potential conflict with any application named 'blank' that might be deployed via Zend Deployment. However, it does have the advantage of being able to do it ahead of time in preparation for the upgrade to IBM i 7.2. The IncludeOptional
directive is not valid in Apache 2.2, so it cannot be substituted in the configuration prior to the upgrade.