In the last post, I discussed my reasoning for switching back to Apache from Cherokee. In this post, I’ll be talking about mod_macro [cri.ensmp.fr], and how it makes configuring Apache fairly easy, and making tweaks dead simple. One of the big complains about Apache is the difficulty in making changes to all virtual hosts on a server. mod_macro not only makes adding new virtual servers easy, it makes tweaking all of them trivial. Read on for a quick tutorial on mod_macro.

The first step, of course, is to install mod_macro. Both Debian and Ubuntu include mod_macro as libapache2-mod-macro, so it’s just an apt-get install libapache2-mod-macro away. It’s also included in Gentoo as www-apache/mod_macro.

Next, make sure you enable mod_macro in your Apache configuration. This part is distro dependent as well. On Debian and Ubuntu, run a2enmod macro. In Gentoo, add -DMACRO to Apache’s command-line options in /etc/conf.d/apache.

Once mod_macro is enabled, you can define your own macros. For the sake of brevity, I won’t be telling you where to put these configuration snippets. In Debian/Ubuntu I use /etc/apache2/sites-available/{macros,vhosts} to define my macros and use them, respectively, and symlink them to /etc/apache2/sites-enabled/{000-macros,010-vhosts} respectively.

Macros are defined in Macro blocks, for example:

<Macro MacroName $arg1 $arg2>
    SomeStatement $arg1
    SomeOtherStatement $arg2
</Macro>

You can then use the macro with Use MacroName foo bar, which would be equivalent to:

SomeStatement foo
SomeOtherStatement bar

It’s important to note that mod_macro doesn’t actually write the expanded macros to a file. The expansions will only be seen by Apache itself, though you can use mod_info [httpd.apache.org] to dump the configuration, which will show you the expanded macros.

A naive implementation of HTTP and HTTPS virtual hosts would use duplicated configuration, such as:

<Macro HTTPandHTTPSMacro $name>
    <VirtualHost *:80>
        ServerName $name
    </VirtualHost>
    <VirtualHost *:443>
        ServerName $name
    </VirtualHost>
</Macro>

Obviously, that’s an over-simplified example. The difference is much more pronounced in real-world configurations. On my servers, I use a uniform layout, where the document root is /srv/www/$host/htdocs, the HTTPS private key is /etc/ssl/private/$host.key, and the HTTPS public key is /etc/ssl/private/$host.crt. You can nest macros and insert them in other contexts, so my macros look like this:

<Macro PHPVHostMixin $host>
    ServerName $host
    DocumentRoot /srv/www/$host/htdocs

    AddHandler application/x-httpd-php5 .php

    <Directory /srv/www/$host/htdocs>
        Order allow,deny
        Allow from all
        AllowOverride All
    </Directory>
</Macro>
<Macro PHPVHost $host>
    <VirtualHost *:80>
        Use PHPVHostMixin $host
    </VirtualHost>
    <VirtualHost *:443>
        Use PHPVHostMixin $host

        SSLEngine On
        SSLCertificateFile    /etc/ssl/private/$host.crt
	SSLCertificateKeyFile /etc/ssl/private/$host.key
    </VirtualHost>
</Macro>

Once you get your macros set up, you can just add Use PHPVHost dririan.com to your configuration file to add a new virtual host! While there may be more work initially, if you ever have to change your configuration, things will be much easier. Editing all PHP virtual hosts in Cherokee means logging into cherokee-admin and manually tweaking every single virtual host. With mod_macro, you can tweak the macro and every virtual host will be updated with it. As usual, any changes to your macros requires you to reload Apache’s configuration.

If you have any questions or comments about using mod_macro, please post a comment below.

Thanks for reading,
dririan