Macro module for Apache
Posted on October 7, 2007
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!
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 </Macro>
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:
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 </Macro>
Use function to go with it:
Use Logfiles tenzer.dk
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.
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 </VirtualHost> </Macro> <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> <Macro cfg $hostname> Include /var/www/conf.d/$hostname.conf </Macro>
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
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
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 tenzer.dk Use VHost cfg example.com # 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!