This module provides macros within apache httpd runtime configuration files. - These macros may have parameters. They are expanded when used (parameters are - substituted by their values given as an argument), and the result is - processed normally.

Provides macros within Apache httpd runtime configuration files, + to ease the process of creating numerous similar configuration + blocks. When the server starts up, the macros are expanded using the + provided parameters, and the result is processed as along with the + rest of the configuration file.

Features

Usage

Definition of a macro:

Macros are defined using <Macro> blocks, which contain the portion of +your configuration that needs to be repeated, complete with variables +for those parts that will need to be substituted.

macro definition within a <Macro> section, following - the httpd configuration style.
user defined names for the macro and its parameters.
macro names are case-insensitive, like httpd directives.
macro parameter names are case sensitive.
macro parameters must have distinct names.
error on empty parameter names.
redefining a macro generates a warning.
macro definitions can be nested... (but what for?)
warn about unused macro parameters.
warn about macro parameter names which prefix one another.
warn if a parameter is not prefixed by any of '$%@' - (good practice).
the available prefixes help deal with interactions with other - directives such as Define.
tip: it may be useful to define a macro parameter with surrounding - braces, say ${foo} so that the name can appear with - surrounding characters such as bla${foo}bla.
warn about empty macro contents.
warns if sections are not properly nested within a macro. - (if it is detected so).
the lexical scope of macro parameters is restricted to the macro text, - it is not forwarded to includes for instance.
arbitrary contents in macros. -
It means you can put perl sections or whatever you like in a macro. - No assumption is made about the lexical structure (quotes, spaces or - whatever) within the macro contents but to expect a set of - backslash-continued independent lines.

- -

Use of a macro:

- -

number of arguments must match the definition.
all occurences of macro parameters are substituted by their values.
in case of conflicts, the longest parameter name is chosen.
macro expansion recursion is detected and stopped (error).
warn about empty arguments when used.
on errors, try to describe precisely where the error occured.
$ and %-prefixed parameters are not - escaped.
@-prefixed parameters are escaped in quotes.

For example, you might use a macro to define a <VirtualHost> block, in order to define +multiple similar virtual hosts:

Removal of a macro definition:

+<Macro VHost $name $domain>
+<VirtualHost *:80>
+    ServerName $domain
+    ServerAlias www.$domain
+
+    DocumentRoot /var/www/vhosts/$name
+    ErrorLog /var/log/httpd/$name.error_log
+    CustomLog /var/log/httpd/name.access_log combined
+>/VirtualHost>
+</Macro>
+

the macro must be already defined.

+ +

Macro names are case-insensitive, like httpd configuration +directives. However, variable names are case sensitive.

+ +

You would then invoke this macro several times to create virtual +hosts:

-<Macro DirGroup $dir $group>
-  <Directory $dir>
-    require group $group
-  </Directory>
-</Macro>
+Use VHost example example.com
+Use VHost myhost hostname.org
+Use VHost apache apache.org
 
-Use DirGroup /www/apache/private private
-Use DirGroup /www/apache/server  admin
+UndefMacro VHost
+

-UndefMacro DirGroup + +

At server startup time, each of these Use +invocations would be expanded into a full virtualhost, as +described by the Macro definition.

+ +

The UndefMacro directive is used so that later +macros using the same variable names don't result in conflicting +definitions.

+ +

A more elaborate version of this example may be seen below in the +Examples section.

+ +

Technical details

+ +

Parameter names should begin with a sigil such as $, +%, or @, so that they are clearly +identifiable, and also in order to help deail with interactions with +other directives, such as the core Define directive. Failure to do so will +result in a warning. Nevertheless, you are encouraged to have a good +knowledge of your entire server configuration in order to avoid reusing +the same variables in different scopes, which can cause confusion.

+ +

Parameters prefixed with either $ or % are +not escaped. Parameters prefixes with @ are escaped in +quotes.

+ +

Avoid using a parameter which contains another parameter as a prefix, +(For example, $win and $winter) as this may +cause confusion at expression evaluation time. In the event of such +confusion, the longest possible parameter name is used.

+ +

If you want to use a value within another string, it is useful to +surround the parameter in braces, to avoid confusion:

+ +

+<Macro DocRoot ${docroot}>
+    DocumentRoot /var/www/${docroot}/htdocs
+</Macro>

@@ -125,6 +139,10 @@ UndefMacro DirGroup

Examples

+ +

Virtual Host Definition

+ +

A common usage of mod_macro is for the creation of dynamically-generated virtual hosts.

@@ -138,8 +156,9 @@ dynamically-generated virtual hosts.

ServerName $host DocumentRoot $dir + # Public document root <Directory $dir> - # do something here... + Require all granted </Directory> # limit access to intranet subdir. @@ -156,6 +175,30 @@ Use VHost example.org 8080 /vhosts/examp Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs + + +

Removal of a macro definition

+ + +

the macro must be already defined.

+ +

+<Macro DirGroup $dir $group>
+  <Directory $dir>
+    Require group $group
+  </Directory>
+</Macro>
+
+Use DirGroup /www/apache/private private
+Use DirGroup /www/apache/server  admin
+
+UndefMacro DirGroup
+

+ + +

Modified: httpd/httpd/trunk/docs/manual/mod/mod_macro.xml.fr URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_macro.xml.fr?rev=1525428&r1=1525427&r2=1525428&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/mod/mod_macro.xml.fr (original) +++ httpd/httpd/trunk/docs/manual/mod/mod_macro.xml.fr Sun Sep 22 20:12:54 2013 @@ -1,7 +1,7 @@ - +

Summary