<summary>
- <p>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.</p>
+ <p>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.</p>
+
</summary>
-<section id="features"><title>Features</title>
-
-<p>Definition of a macro:</p>
-
- <ul>
- <li> macro definition within a <directive type="section">Macro</directive> section, following
- the httpd configuration style.</li>
- <li> user defined names for the macro and its parameters.</li>
- <li> macro names are case-insensitive, like httpd directives.</li>
- <li> macro parameter names are case sensitive.</li>
- <li> macro parameters must have distinct names.</li>
- <li> error on empty parameter names.</li>
- <li> redefining a macro generates a warning.</li>
- <li> macro definitions can be nested... (but what for?)</li>
- <li> warn about unused macro parameters.</li>
- <li> warn about macro parameter names which prefix one another.</li>
- <li> warn if a parameter is not prefixed by any of '<code>$%@</code>'
- (good practice).</li>
- <li> the available prefixes help deal with interactions with other
- directives such as <directive module="core">Define</directive>.</li>
- <li> tip: it may be useful to define a macro parameter with surrounding
- braces, say <code>${foo}</code> so that the name can appear with
- surrounding characters such as <code>bla${foo}bla</code>.</li>
- <li> warn about empty macro contents.</li>
- <li> warns if sections are not properly nested within a macro.
- (if it is detected so).</li>
- <li> the lexical scope of macro parameters is restricted to the macro text,
- it is not forwarded to includes for instance.</li>
- <li> arbitrary contents in macros.
- <p>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.</p></li>
- </ul>
-
-<p>Use of a macro:</p>
-
- <ul>
- <li> number of arguments must match the definition.</li>
- <li> all occurences of macro parameters are substituted by their values.</li>
- <li> in case of conflicts, the longest parameter name is chosen.</li>
- <li> macro expansion recursion is detected and stopped (error).</li>
- <li> warn about empty arguments when used.</li>
- <li> on errors, try to describe precisely where the error occured.</li>
- <li> <code>$</code> and <code>%</code>-prefixed parameters are not
- escaped.</li>
- <li> <code>@</code>-prefixed parameters are escaped in quotes.</li>
- </ul>
-
-<p>Removal of a macro definition:</p>
+<section id="usage"><title>Usage</title>
- <ul>
- <li> the macro must be already defined.</li>
- </ul>
+<p>Macros are defined using <directive
+type="section">Macro</directive> 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.</p>
+
+<p>For example, you might use a macro to define a <directive
+type="section">VirtualHost</directive> block, in order to define
+multiple similar virtual hosts:</p>
<highlight language="config">
-<Macro DirGroup $dir $group>
- <Directory $dir>
- require group $group
- </Directory>
+<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>
+</highlight>
-Use DirGroup /www/apache/private private
-Use DirGroup /www/apache/server admin
+<p>Macro names are case-insensitive, like httpd configuration
+directives. However, variable names are case sensitive.</p>
-UndefMacro DirGroup
+<p>You would then invoke this macro several times to create virtual
+hosts:</p>
+
+<highlight language="config">
+Use VHost example example.com
+Use VHost myhost hostname.org
+Use VHost apache apache.org
+
+UndefMacro VHost
+</highlight>
+
+<p>At server startup time, each of these <directive>Use</directive>
+invocations would be expanded into a full virtualhost, as
+described by the <directive>Macro</directive> definition.</p>
+
+<p>The <directive>UndefMacro</directive> directive is used so that later
+macros using the same variable names don't result in conflicting
+definitions.</p>
+
+<p>A more elaborate version of this example may be seen below in the
+Examples section.</p>
+
+</section>
+
+<section id="details"><title>Technical details</title>
+
+<p>Parameter names should begin with a sigil such as <code>$</code>,
+<code>%</code>, or <code>@</code>, so that they are clearly
+identifiable, and also in order to help deail with interactions with
+other directives, such as the core <directive
+module="core">Define</directive> 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.</p>
+
+<p>Parameters prefixed with either <code>$</code> or <code>%</code> are
+not escaped. Parameters prefixes with <code>@</code> are escaped in
+quotes.</p>
+
+<p>Avoid using a parameter which contains another parameter as a prefix,
+(For example, <code>$win</code> and <code>$winter</code>) as this may
+cause confusion at expression evaluation time. In the event of such
+confusion, the longest possible parameter name is used.</p>
+
+<p>If you want to use a value within another string, it is useful to
+surround the parameter in braces, to avoid confusion:</p>
+
+<highlight language="config">
+<Macro DocRoot ${docroot}>
+ DocumentRoot /var/www/${docroot}/htdocs
+</Macro>
</highlight>
</section>
-<section id="examples"><title>Examples</title>
+<section id="examples">
+<title>Examples</title>
+
+<section>
+<title>Virtual Host Definition</title>
<p>A common usage of <module>mod_macro</module> is for the creation of
dynamically-generated virtual hosts.</p>
ServerName $host
DocumentRoot $dir
+ # Public document root
<Directory $dir>
- # do something here...
+ Require all granted
</Directory>
# limit access to intranet subdir.
Use VHost example.org 8080 /vhosts/example/htdocs
Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs
</highlight>
+</section> <!-- Vhosts -->
-</section>
+<section>
+<title>Removal of a macro definition</title>
+
+ <ul>
+ <li> the macro must be already defined.</li>
+ </ul>
+
+<highlight language="config">
+<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
+</highlight>
+
+</section> <!-- UndefMacro -->
+
+</section> <!-- Example -->
<!-- Macro -->
<directivesynopsis type="section">
</highlight>
</usage>
</directivesynopsis>
+
</modulesynopsis>
projects / apache / commitdiff