Apache 2.2 module mod_macro 1.1.10

Contents

• Summary
• Examples
• Benefits
• Download
• License
• Install
• History
• Motivation
• Specification
• Author

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 within apache runtime configuration files.
The syntax is a natural extension to apache html-like configuration style.

## Define a VHost Macro.

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

    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

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

• smaller configuration files to maintain.
• less bugs due to copy-pastes only partially updated.
• better readability. for instance: Use AllowLocalAccess might be considered clearer than
  allow from 192.54.172.0/24 192.54.148.0/24 10.0.0.0/8
• all this not at the price of perl or m4 programming.

The current version for Apache 2.2 is 1.1.10. 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. If you have version 1.0.13 or earlier, consider upgrading.
It is available is several formats, signed with

• mod_macro-1.1.10.tar.bz2 (13KB)
• mod_macro-1.1.10.tar.gz (14KB)
• mod_macro-1.1.10.zip (16KB)
• mod_macro-1.1.10.tar.Z (22KB)
• mod_macro-1.1.10.tar (60KB)

You can also browse the source directory:

• README
• INSTALL
• CHANGES
• LICENSE
• mod_macro.c
• mod_macro.html

This software is made available as a third-party apache module, under the terms of a BSD-style license, just like Apache. The license is included in the distribution. See http://www.opensource.org/ for a discussion about open source licenses.

Versions prior to 1.1.0 were distributed under the terms of the GNU General Public License version 2 or later. However it does not allow commercial version of the software to be derived, hence the switch.

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

• download the latest mod_macro release:

  http://www.coelho.net/mod_macro/mod_macro-latest.tar.gz

• uncompress the distribution tar file if necessary.

  prompt> gunzip mod_macro-latest.tar.gz

• untar the distribution tar file along the apache source tree.

  prompt> tar xf mod_macro-latest.tar

• You should read the README, LICENSE and INSTALL files provided with the distribution. You may also browse the source code to check for any backhole or whatever.

• run apxs on the module source to compile, install and add the module

  prompt> apxs -cia mod_macro-1.1.10/mod_macro.c

• you may also want to install the html documentation.

  prompt> cp mod_macro-1.1.10/mod_macro.html apache_2.2.0/manual/mod/

  and maybe update apache_2.2.0/htdocs/manual/mod/index.html to add a reference to the mod_macro.html file.

• 1.1.10 2007/12/24: escape @-arguments, useful in some case pointed out by Marc Stern.
• 1.1.9 2007/11/27: fix Error/Warning coredump, because Apache 2.2 has changed how to access the current filename and line number. Signaled by Dirk Schreiner and Marc Stern. Major update of the license to receive postcards.
• 1.1.8 2006/08/07: some cleanup suggested by Jorge Schrauwen for win64 compilation, and Tim Carey-Smith for the web site.
• 1.1.7 2006/02/28: port to apache 2.2. Macro directives are handled while reading the configuration file. A few casts to avoid warnings.
• 1.1.6 2004/07/15: license 'avertising clause' fix for crowbar at gmail dot com.
• 1.1.5 2003/09/09: some improvements for MSW by Marc M. Adkins.
• 1.1.4 2002/09/10: A very quick ugly fix to the initialization for 2.0.40...
• 1.1.3 2002/06/01: port to apache 2.0. very few changes in the end, but I had to update my linux box so as to be able to compile apache. I need a major update to take advantage of the new apache infrastructure, but in the meantime this is a working version.
• 1.1.2b 2004/07/16: license 'avertising clause' fix for crowbar at gmail dot com.
• 1.1.2 2001/10/16: fix by Axel Beckert for apache 1.3.22.
• 1.1.1 1999/01/30: the tared directory includes the version number.
• 1.1.0 1999/01/11: release for 1.3.4. switched to a BSD-style license.
• 1.0.18 1998/12/24: warns about bad nesting. more tests.
• 1.0.17 1998/12/24: more comments and docs fixes.
• 1.0.16 1998/12/23: more warnings (empty contents, arg without prefixes). maybe too much, so a define can avoid them.
• 1.0.15 1998/12/22: patch to apache included. docs updated.
• 1.0.14 1998/12/21: I had to change internals:-( see comments in mod_macro.c
• 1.0.13 1998/12/19: I hope better error messages.
• 1.0.12 1998/12/19: cosmetics. doc++.
• 1.0.11 1998/12/19: error and warning added. more tests.
• 1.0.10 1998/12/18: warn or error on empty arguments. more tests.
• 1.0.9 1998/12/18: warn about unused arguments. how nice! more tests.
• 1.0.8 1998/12/18: more tests. style fixes. longest argument substituted instead of first. more and better warnings.
• 1.0.7 1998/12/18: more tests. style fixes in the source code.
• 1.0.6 1998/12/17: bug fixes, mainly to detect bad nesting. also macros are allowed anywhere now.
• 1.0.5 1998/12/16: macro redefinitions allowed with a warning.
• 1.0.4 1998/12/16: more tests. example in home page.
• 1.0.3 1998/12/16: better home page. GNU GPL.
• 1.0.2 1998/12/16: better documentation. made case insensitive.
• 1.0.1 1998/12/15: initial version.

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. (Keep It Simple, Stupid!)

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

• compatible with the current apache configuration style, defined as:
  • ascii textual configuration files (no external preprocessor).
  • few assumptions about lexical conventions (backslash-continued-line with leading case-insensitive keywords).
  • comments on '#'-started lines.
  • properly nested html-like (not looking too close) sections.
• the result looks like:
  • <Macro ...> ... </Macro>
  • Use ...
• simple specification (hummm;-)
  • one separate case-insensitive name space for macros (no interaction).
  • usual lexical conventions for macro arguments.
  • minimum lexical convention for macro contents (all argument string occurences are coldly substituted in Use).
  • substitution of the longest argument if several match and conflict.
  • macro contents should be properly nested.
• simple and safe implementation.
  • but clear and precise error messages (that is not always easy!).
  • detection of recursions in macro expansions.
  • no argument expansion within just substituted arguments.
  • use of ap_* where appropriate (in ap_*, it seems that the code is the doc;-).

The author and maintainer of this module is: Fabien Coelho
mod_macro: http://www.coelho.net/mod_macro/
E-mail: mod.macro@coelho.net
URL: http://www.coelho.net/
PGP: signature

CRI, École des mines de Paris,
35, rue Saint-Honoré,
77305 Fontainebleau cedex,
FRANCE.