Jangro.com

CPanel EasyApache and Customizing httpd.conf

Warning: I’m geeking out for a bit here with a technical entry about editing apache configuration files in Cpanel. I barely found anything out on the Interwebs about this, so I thought I’d document what I learned.

All of our web servers run the CPanel host management software. It’s nice having so much of the server configuration options configurable with a web interface.

But sometimes, I need to make changes directly to the apache server configuration files (httpd.conf). This has never been a problem, as long as I didn’t screw anything up of course. I just edit the configuration file, restart apache and move on with life.

That is, until recently. At some point, the CPanel software was updated so that it builds the httpd.conf file based on the information that it gathers from the CPanel configuration settingsf. Now, if you simply edit this file, CPanel WILL overwrite your changes at some later time, breaking whatever functionality you were specifying.

There are all sorts of warnings now in the httpd.conf file instructing that it is no longer appropriate to edit this file directly.

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# Direct modifications to the Apache configuration file may be lost upon subsequent regeneration of the configuration file. To have modifications retained, all modifications must be checked into the configuration system by running: #
# /usr/local/cpanel/bin/apache_conf_distiller --update #
# To see if your changes will be conserved, regenerate the Apache configuration file by running:
#
# /usr/local/cpanel/bin/build_apache_conf #
# and check the configuration file for your alterations. If your changes have been ignored, then they will need to be added directly to their respective template files. #
# This configuration file was built from the following templates:
# /var/cpanel/templates/apache1/main.default
# /var/cpanel/templates/apache1/main.local
# /var/cpanel/templates/apache1/vhost.default
# /var/cpanel/templates/apache1/vhost.local
# /var/cpanel/templates/apache1/ssl_vhost.default
# /var/cpanel/templates/apache1/ssl_vhost.local
#
# Templates with the '.local' extension will be preferred over templates with the '.default' extension.
# The only template updated by the apache_conf_distiller is main.default. #
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

I’m not sure exactly when this happened, though I think it was in the past few months. Or at least my hosting providers updated CPanel to this version recently.

You CAN edit the main httpd.conf settings as long as you run the apache_conf_distiller script to check in the changes.

You CANNOT edit the virtualHost settings and save them with that same script, however. They will not stick.

In order to make customizations to any VirtualHost sections of the httpd.conf file, you must create include files.

The documentation on this is quite poor, but here’s what I figured out.

If you want to change the default VirtualHost settings, either globally, for a specific user, or for a specific domain, you must do so by overriding those settings with separate include file, placed in a very specific directory location. Once you create the appropriate include files in the correct directory tree, a script will add those include files to your httpd.conf file for you.

To me, I only ever want to edit the vhost behavior on a single domain, so I’ll cut to the chase here and show that example:

First, create the following directory struture and file:

/usr/local/apache/conf/userdata/(ssl|std)/(1|2)/<user>/<domain>/custom.conf

for Standard (non-ssl), apache version 1, user called abc, domain called abc.com it would look like this:

/usr/local/apache/conf/userdata/std/1/abc/abc.com/custom.conf

Then put your custom directives in that file. In my case, I wanted to handle wildcard subdomains, so I just added this one line:

ServerAlias *.abc.com

Now, run the following script:

/scripts/ensure_vhost_includes --user=joe

And the appropriate include directives will get added to the VirtualHost sections of your httpd.conf file.

I ran the distiller, just to make sure the data was saved, though that may not be necessary.

If you enjoyed this post, please subscribe to my RSS feed