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.
## 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.
Use AllowLocalAccess
might be considered clearer thanallow from 192.54.172.0/24 192.54.148.0/24 10.0.0.0/8
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.
The current version for Apache 2.4 is 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.
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!
Installing the mod_macro module with apache is rather simple,
especially with apxs
.
Here is a sample direct installation with apache 2.4:
http://people.apache.org/~fabien/mod_macro/mod_macro-latest.tar.gz
prompt> tar xzvf mod_macro-1.2.1.tar.gz
apxs
on the module source to compile, install and add
the module.
prompt> apxs -cia mod_macro-1.2.1/mod_macro.c
prompt> cp mod_macro-1.2.1/mod_macro.html apache_2.4/manual/mod/
and maybe update apache_2.4/htdocs/manual/mod/index.html
to
add a reference to the mod_macro.html
file.
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.
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.