Defining Macros With mod_macro In Apache 

This guide is about 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 can't only be used to print a few lines in Apache's configuration, it can also be used for entire <VirtualHost> declarations, like this:

<Macro VHost $type $hostname>
<VirtualHost *>
   ServerAdmin [email protected]$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 VirtualHosts would look like this:

Use VHost dir
Use VHost cfg

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 VirtualHosts.

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

Share this page:

Suggested articles

1 Comment(s)

Add comment


By: Kris

Really helpful tutorial... Saved me a lot of work!