Macro module for Apache

Posted on October 7, 2007. Reading time: 4 minutes

This guide is about the wonderful mod_macro, which makes the job of managing an Apache webserver much easier, or just for the home developer with several test pages or projects.

I will explain how to get it running and give some examples of how I use the module, to help you get started with using it.


First we need to get the module installed, since it is not installed in a default Debian/Ubuntu installation. I presume you already have Apache2 installed, otherwise you should install that first. We can use APT to install the module, just run the following command as root:

apt-get install libapache2-mod-macro

Next we need to activate the module and restart Apache:

a2enmod macro
/etc/init.d/apache2 restart

And you are ready to use macros!

Basic usage

Before we are ready to make our config files, you should first learn how to use mod_macro. It basically adds one new function and a new tag, which now can be used in Apache's config files. The function Use and the tag <Macro>. We start of with the tag which is used to create a new macro. A simple static macro could look like the following:

<Macro Logfile>
    CustomLog /var/log/apache2/access.log combined
    ErrorLog /var/log/apache2/error.log
    LogLevel warn

The macro simply declares that the macro called Logfile contains the text within the Macro tags. In order to use the macro you just put the following line in your config file, where ever you normally would have put the lines from your macro:

Use Logfile

When you then reload Apache and it looks through the configuration files, then it automatically converts Use Logfile to the lines you have defined in your macro.

That was simple, but what do you do if you don't want all sites to log to the same file? You could create a logfile for each site, by declaring a variable which is then used in the macro:

<Macro Logfiles $sitename>
    CustomLog /var/log/apache2/$sitename-access.log combined
    ErrorLog /var/log/apache2/$sitename-error.log
    LogLevel warn

And the Use function to go with it:

Use Logfiles

Neat, don't you think? If you then want to change the path to your logfiles, you only have to change it in your macro, and not in every config file you have got. The syntax for Use looks like this:

Use <Macroname> [Variable 1] [Variable 2] ... [Variable x]

Which basically means that you have to supply a name for the macro you are using, but the variables are optional.

A thing you need to remember when making macros, is that the file defining your macros needs to be included in Apache's configuration files somewhere, or else you will not be able to use them. I would suggest you to make a file called macro.conf inside the folder /etc/apache2/conf.d/, since all files in that folder automatically get included by Apache.

Advanced usage

Macros are not limited to only be used for printing a few lines in Apache's configuration, it can also be used for entire VirtualHost declarations, like this:

<Macro VHost $type $hostname>
    <VirtualHost *>
        ServerAdmin webmaster@$hostname

        Use $type $hostname

        ServerSignature On

        ServerName $hostname
        ServerAlias www.$hostname

<Macro dir $hostname>
    DocumentRoot /var/www/$hostname

    CustomLog /var/log/apache2/$hostname-access.log combined
    ErrorLog /var/log/apache2/$hostname-error.log
    LogLevel warn

<Macro cfg $hostname>
    Include /var/www/conf.d/$hostname.conf

I should probably explain this since it can seem quite complicated at first sight. The macros are supplied with two variables, the first one called $type, which can either be set to dir or cfg, and the second variable called $hostname would be the hostname of the site, without "www." in front of it. The $hostname variable sets the name of the logfiles and also defines the ServerName with the domainname, and even adds a ServerAlias with "www." prefixed. The purpose of the $type variable is to give you the choice between making a custom config file for the VirtualHost, which would then be placed in /var/www/conf.d/$hostname.conf, or to use a predefined path for the DocumentRoot (/var/www/$hostname/).

This makes it very easy to get an overview of which sites you have added in Apache, since the list of virtual hosts would look like this:

Use VHost dir
Use VHost cfg
# etc...

This also makes it easier to script adding and deleting sites to the server, since you only have to look for one single line in the Apache configuration.

Do note that the macro module can be used in all of Apache's config files and not only for setting up virtual host.

I hope that you found this guide helpful, and please let me know of the ways you use mod_macro in your setup!