Have you ever wanted to have functions or templates that’d really help with not repeating similar configuration blocks with super minor differences in your Apache Web Server config files ? The best use case is when your machine (single IP Address) is serving multiple domains. For this you must have multiple virtual hosts sections (VirtualHost) but with literally minor differences in the domain (ServerName) and the path to serve files (DocumentRoot).

mod_macro to the rescue! This module provides the ability to put macros within your httpd configuration files containing portions that you want to repeat with minor variations. The defined macros may accept a few arguments (variables) for a little dynamicity of the templates defined within.

Usage

Note: Before using the module, you’ll need to enable it first.

Let’s quickly review the syntax of Macro and Use directives that are used to define a macro and use one, respectively.

# Define a macro
<Macro name [par1 .. parN]>
    ... Code to be repeated ...
</Macro>

# Use a macro
Use name [value1 ... valueN]

The Macro directive accepts a name and a bunch of parameters. It is highly recommended that the parameters specified for Macro are prefixed with $, % or @ characters to avoid any kind of confusion. On the other hand, the Use directive sort of invokes the macro replacing itself with the expanded versions of config snippets defined within the macro. With Use, we must pass the macro name and arguments for each macro parameter.

Let’s quickly hop on to the usage. Imagine you had multiple websites/apps being served off the same server.

<Macro VHost $app $domain>
<VirtualHost *:80>
        ServerName $domain
        ServerAlias www.$domain

        DocumentRoot /home/public/$app

        <Directory /home/public/$app>
                Require all granted
        </Directory>

        ErrorLog /var/logs/httpd/$app.error.log
        CustomLog /var/logd/httpd/$app.access.log combined
</VirtualHost>
</Macro>

Use VHost app1 site1.com
Use VHost app2 site2.com
Use VHost app3 site3.com

UndefMacro VHost

We define a macro called VHost that accepts two arguments – $app and $domain. When its time to use it, we make use of the Use directive thrice and pass the macro name along with the appropriate arguments. During each server startup, the Use invocations are expanded into full virtual host configurations as defined by the macro. Hence we’ll end up having three <VirtualHost> sections on server startup. You can test/debug that as well.

This allows us to dynamically configure and create multiple virtual hosts that are mostly common in terms of configuration except few differences in the server names, document roots, directories, etc. that can be dynamically set. So if you ever find yourself repeating similar virtual host blocks multiple times, you now know how to use macros or templates to reduce your configuration code.

It is kind of recommended to unset or undefine the macro definitions after the usage via the UndefMacro directive. That’s what we’ve done in the last line of the code block above. As long as your configuration is short, sweet and clean and you know what you’r doing, its probably fine to skip it.

BTW, macros can be used for all sorts of configuration directives and blocks, not just virtual hosts.

Tip: For better organisation you may want to put your macros in separate files and then include inside the main config file (httpd.conf or apache2.conf).