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

Verify you have a compatible version of Zend Server

IBM i 7.2 requires version 7.0.0 or higher of Zend Server.  IBM i 7.3 requires version 8.5.3 or higher of Zend Server. If you are running an earlier version of Zend Server, please upgrade.

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:


/www/zendphp7/conf/httpd.conf

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


/usr/local/zendphp7/etc/sites.d/zend-default-vhost-10080.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:


/www/zendsvr6/conf/httpd.conf

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


/usr/local/zendsvr6/etc/sites.d/zend-default-vhost-10080.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:

Options +Indexes FollowSymLinks

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:

Options +Indexes +FollowSymLinks

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:

/usr/local/$zendxxn/etc/sites.d/http/$vhname/$port/

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:

/usr/local/zendphp7/etc/sites.d/http/__default__/0/

An application deployed to a virtual host named MySSLHost.com at port 443 in Zend Server 8.5 would be found here:

/usr/local/zendsvr6/etc/sites.d/http/MySSLHost.com/443/

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:

/usr/local/zendsvr6/etc/sites.d/http/__default__/0/98_samples.conf

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:

find /usr/local/zendphp7/etc/sites.d -name *.conf

For Zend Server 6 to 8.5:

find /usr/local/zendsvr6/etc/sites.d -name *.conf


Learn more about these changes to the Options

In the example given above, it is perfectly OK to add the plus sign to the FollowSymLinks option.  However, if you find other occurrences of mixed option types, or just want to know more about this change you are making to your configs, please read the documentation for the Options directive to understand what it means to use the plus and minus signs:
https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzaie/rzaiemod_core.htm#options


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:

/usr/local/zendsvr6/etc/sites.d/globals-blank.conf
/usr/local/zendsvr6/etc/sites.d/vhost_blank.conf
/usr/local/zendsvr6/etc/sites.d/http/_default_/0/blank.conf

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.