mod_macro.html.en revision d5e8240ee767cced65a45a2b9d590ca08b3d3859
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
a78048ccbdb6256da15e6b0e7e95355e480c2301nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
a78048ccbdb6256da15e6b0e7e95355e480c2301nd This file is generated from xml source: DO NOT EDIT
a78048ccbdb6256da15e6b0e7e95355e480c2301nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<script src="/style/scripts/prettify.js" type="text/javascript">
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p><span>Available Languages: </span><a href="/en/mod/mod_macro.html" title="English"> en </a> |
053bfa8a288528fafab2b7a032c15116bb5de711nd<a href="/fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides macros within apache httpd runtime configuration files</td></tr>
4b575a6b6704b516f22d65a3ad35696d7b9ba372rpluem<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
4b575a6b6704b516f22d65a3ad35696d7b9ba372rpluem<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>macro_module</td></tr>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_macro.c</td></tr></table>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>Provides macros within Apache httpd runtime configuration files,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd to ease the process of creating numerous similar configuration
a78048ccbdb6256da15e6b0e7e95355e480c2301nd blocks. When the server starts up, the macros are expanded using the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd provided parameters, and the result is processed as along with the
a78048ccbdb6256da15e6b0e7e95355e480c2301nd rest of the configuration file.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<div id="quickview"><h3 class="directives">Directives</h3>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<li><img alt="" src="/images/down.gif" /> <a href="#macro"><Macro></a></li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<li><img alt="" src="/images/down.gif" /> <a href="#undefmacro">UndefMacro</a></li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<li><img alt="" src="/images/down.gif" /> <a href="#use">Use</a></li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<li><img alt="" src="/images/down.gif" /> <a href="#usage">Usage</a></li>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh<li><img alt="" src="/images/down.gif" /> <a href="#tips">Tips</a></li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>Macros are defined using <code class="directive"><Macro></code> blocks, which contain the portion of
a78048ccbdb6256da15e6b0e7e95355e480c2301ndyour configuration that needs to be repeated, complete with variables
a78048ccbdb6256da15e6b0e7e95355e480c2301ndfor those parts that will need to be substituted.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>For example, you might use a macro to define a <code class="directive"><VirtualHost></code> block, in order to define
a78048ccbdb6256da15e6b0e7e95355e480c2301ndmultiple similar virtual hosts:</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<Macro VHost $name $domain>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<VirtualHost *:80>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd ServerName $domain
a78048ccbdb6256da15e6b0e7e95355e480c2301nd ServerAlias www.$domain
a78048ccbdb6256da15e6b0e7e95355e480c2301nd>/VirtualHost>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd</Macro>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>Macro names are case-insensitive, like httpd configuration
a78048ccbdb6256da15e6b0e7e95355e480c2301nddirectives. However, variable names are case sensitive.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>You would then invoke this macro several times to create virtual
a78048ccbdb6256da15e6b0e7e95355e480c2301ndUse VHost example example.com
a78048ccbdb6256da15e6b0e7e95355e480c2301ndUse VHost myhost hostname.org
a78048ccbdb6256da15e6b0e7e95355e480c2301ndUse VHost apache apache.org
a78048ccbdb6256da15e6b0e7e95355e480c2301ndUndefMacro VHost
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>At server startup time, each of these <code class="directive">Use</code>
a78048ccbdb6256da15e6b0e7e95355e480c2301ndinvocations would be expanded into a full virtualhost, as
a78048ccbdb6256da15e6b0e7e95355e480c2301nddescribed by the <code class="directive">Macro</code> definition.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>The <code class="directive">UndefMacro</code> directive is used so that later
a78048ccbdb6256da15e6b0e7e95355e480c2301ndmacros using the same variable names don't result in conflicting
a78048ccbdb6256da15e6b0e7e95355e480c2301nddefinitions.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>A more elaborate version of this example may be seen below in the
a78048ccbdb6256da15e6b0e7e95355e480c2301ndExamples section.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>Parameter names should begin with a sigil such as <code>$</code>,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<code>%</code>, or <code>@</code>, so that they are clearly
a78048ccbdb6256da15e6b0e7e95355e480c2301ndidentifiable, and also in order to help deail with interactions with
a78048ccbdb6256da15e6b0e7e95355e480c2301ndother directives, such as the core <code class="directive"><a href="/mod/core.html#define">Define</a></code> directive. Failure to do so will
a78048ccbdb6256da15e6b0e7e95355e480c2301ndresult in a warning. Nevertheless, you are encouraged to have a good
a78048ccbdb6256da15e6b0e7e95355e480c2301ndknowledge of your entire server configuration in order to avoid reusing
a78048ccbdb6256da15e6b0e7e95355e480c2301ndthe same variables in different scopes, which can cause confusion.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>Parameters prefixed with either <code>$</code> or <code>%</code> are
a78048ccbdb6256da15e6b0e7e95355e480c2301ndnot escaped. Parameters prefixes with <code>@</code> are escaped in
a78048ccbdb6256da15e6b0e7e95355e480c2301ndquotes.</p>
a78048ccbdb6256da15e6b0e7e95355e480c2301nd<p>Avoid using a parameter which contains another parameter as a prefix,
a78048ccbdb6256da15e6b0e7e95355e480c2301nd(For example, <code>$win</code> and <code>$winter</code>) as this may
a78048ccbdb6256da15e6b0e7e95355e480c2301ndcause confusion at expression evaluation time. In the event of such
a78048ccbdb6256da15e6b0e7e95355e480c2301ndconfusion, the longest possible parameter name is used.</p>
053bfa8a288528fafab2b7a032c15116bb5de711nd<p>If you want to use a value within another string, it is useful to
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjungsurround the parameter in braces, to avoid confusion:</p>
727872d18412fc021f03969b8641810d8896820bhumbedooh<Macro DocRoot ${docroot}>
0d0ba3a410038e179b695446bb149cce6264e0abnd</Macro>
0d0ba3a410038e179b695446bb149cce6264e0abnd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh<h2><a name="examples" id="examples">Examples</a></h2>
0d0ba3a410038e179b695446bb149cce6264e0abnd<p>A common usage of <code class="module"><a href="/mod/mod_macro.html">mod_macro</a></code> is for the creation of
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedoohdynamically-generated virtual hosts.</p>
0d0ba3a410038e179b695446bb149cce6264e0abnd## Define a VHost Macro for repetitive configurations
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd<Macro VHost $host $port $dir>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd Listen $port
a78048ccbdb6256da15e6b0e7e95355e480c2301nd <VirtualHost *:$port>
<div class="directive-section"><h2><a name="Macro" id="Macro"><Macro></a> <a name="macro" id="macro">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a configuration file macro</td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<div class="directive-section"><h2><a name="UndefMacro" id="UndefMacro">UndefMacro</a> <a name="undefmacro" id="undefmacro">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine a macro</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UndefMacro <var>name</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<div class="directive-section"><h2><a name="Use" id="Use">Use</a> <a name="use" id="use">Directive</a></h2>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<p><span>Available Languages: </span><a href="/en/mod/mod_macro.html" title="English"> en </a> |
<a href="/fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_macro.html';
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
<p class="apache">Copyright 2013 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--