[APACHE SERVER]

Apache module mod_macro

This module is integrated into Apache HTTP Server from version 2.4.6. See its online documentation.

The following applies to prior versions.

Contents


Summary

mod_macro is a third-party module to the Apache Http Server, distributed with a BSD-style license like Apache.
It allows the definition and use of macros (configuration templates) within apache runtime configuration files.
The syntax is a natural extension to apache html-like configuration style.


Examples

Here is a sample use of mod_macro within a configuration file:
## Define a VHost Macro for repetitive configurations

<Macro VHost $host $port $dir>
  Listen $port
  <VirtualHost *:$port>

    ServerName $host
    DocumentRoot $dir

    <Directory $dir>
      # do something here...
    </Directory>

    # limit access to intranet subdir.
    <Directory $dir/intranet>
      order deny,allow
      deny from all
      allow from 10.0.0.0/8
    </Directory>
  </VirtualHost>
</Macro>

## Use of VHost with different arguments.

Use VHost www.apache.org 80 /projects/apache/web
Use VHost www.perl.com 8080 /projects/perl/web
Use VHost www.ensmp.fr 1234 /projects/mines/web

## One may choose not to put the vhost tag in the macro
## So as to keep the VirtualHost structure apparent and
## allow to add more configuraiton directives after the
## common ones.

<Macro VHostSetup $name>
  ServerName www.$name.com
  ServerAlias $name.com
  DocumentRoot /projects/$name/www
  <Directory /projects/$name/www>
    # something
  </Directory>
  # more common stuff...
</Macro>

<VirtualHost *>
  Use VHostSetup google
  # more particular stuff here for google
</VirtualHost>

<VirtualHost *>
  Use VHostSetup facebook
  # more particular stuff here for facebook
</VirtualHost>

## May also be helpful: Error directive

<IfModule !mod_security.c>
  Error "Argh! mod_security is not loaded!"
</IfModule>

## Done.

A simple example is presented in issue 144 of Apache Week.

Another example shows how to simplify mod_perl configuration with mod_macro.

Some promotion by Jim Jagielski at ApacheCon reported on Trouble Shooters by Steve Litt.

A blog post by Patrick Allaert who noted that the macro definition does not need to be perfectly nested. This can be used to provide a common prefix definition to virtual hosts, and then to append other directives.

Another blog post by Mads Sülau Jørgensen presents the module.

One more blog post by David Anderson who presents a neat configuration.

An article by Jeppe Toustrup with advanced parametric macros, that is a macro argument is used as a macro name in the definition.

Some stuff in Chinese, German, Greek, French, Italian, Polish, Japanese, Portuguese, Russian.


Benefits

You may have several benefits from using macros in configuration files.

Documentation

See the full documentation for the module.

For simple repetitive sites, a macro can define the whole virtual host configuration, so that each site is a one-liner with appropriate arguments.

For complex sites, a good practice is to have thematic macros which encompass several related directives, and to accumulate their use within a virtual host to define its overall behavior.


Download

For Apache 2.4 from 2.4.6, the module is included in Apache distribution. For Apache 2.4 prior 2.4.6, use version 1.2.1. For Apache 2.2, use 1.1.11. For Apache 2.0, use 1.1.6. It won't work with Apache 1.3 for which you should use version 1.1.2.


License

This software is made available as a third-party apache module, under the terms of a BSD-style license, just like Apache. The Open Source license is included in the distribution.

Versions prior to 1.1.0 were distributed under the terms of the GNU General Public License version 2 or later. However it is stricter than Apache License, hence the switch to match the mother project.

By the way, if you are happy with this software, I like to receive postcards from all over the world. Please send me one to the address at the bottom of the page!


Install

Installing the mod_macro module with apache is rather simple, especially with apxs. Here is a sample direct installation with apache 2.4:


History of versions


Motivation

I hate copy-paste.

When configuring the apache server I often have to copy-paste some parts, especially with virtual hosts to enable similar features or options. In order to avoid this, I would need some kind of macro capabilities in the server runtime configuration files.

Apache already includes preprocessor features such as <IfDefine> and Include. This is not enough for me.

There are several existing processors with macro capabilities such as cpp and m4. However, they need assumptions about the lexical structure of the files, that we cannot have with apache. Moreover they cannot be integrated with the apache html-like configuration style.

The apache-perl integration allows <Perl> sections within the configuration file. These sections could be of some use with subroutines and so, but it requires mod_perl and to change my habits a lot. Furthermore, I do not like perl.

So I end up with deciding to implement a macro extension module to apache.

In my opinion, this stuff MUST NOT grow to a full language.

It should just grow to what is needed to manage configuration files simply and elegantly, and to avoid unnecessary copy-pastes. I may consider adding a foreach repetition section, if proven useful. I may also consider reimplementing a working Include since the current one does not work properly (bug #3169/#3578).

But no while, no arithmetics, no variables, no recursion, no goto, no sql, no extended regexpr... Never: I'll stick to the KISS Principle.

My purpose is easier apache configuration file maintenance, not general purpose programming. If you want actual programming, consider perl sections (or embed another programming language like tcl or python).

Note that this module does not aim at substituting variables anywhere in the configuration. Apache can substitute defined variables in directives with Define, or environment variable set before starting the server. This feature was provided by mod_define by Ralf S. Engelschall and Christian Reiber for Apache 1.3, and ported to Apache 2.0 and 2.2 by Rainer Jung. It is now included in the core distribution with Apache 2.4.


Specification

I gave myself the following requirements:

Author

The author and maintainer of this module is Fabien Coelho
E-mail: mod-dot-macro-at-coelho-dot-net
Homepage: http://www.coelho.net/
Homepage at Apache: http://people.apache.org/~fabien/
Homepage at work: http://www.cri.mines-paristech.fr/~coelho/
mod_macro: http://people.apache.org/~fabien/mod_macro
Snail mail:
CRI, Maths & Systems, MINES ParisTech,
35, rue Saint-Honoré,
77305 Fontainebleau cedex,
FRANCE.