mod_macro.html.en revision 6d92f6ca27b32822e9a78596f4ab561cd65b7016
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
cfbca4e518f4981f435e93e434f17271e6efc138rbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
cfbca4e518f4981f435e93e434f17271e6efc138rbowen This file is generated from xml source: DO NOT EDIT
cfbca4e518f4981f435e93e434f17271e6efc138rbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<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" />
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<script src="/style/scripts/prettify.js" type="text/javascript">
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<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>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<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>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<p><span>Available Languages: </span><a href="/en/mod/mod_macro.html" title="English"> en </a> |
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<a href="/fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
e60187855fd0488f48f37e88acde742754308d39rbowen<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>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>macro_module</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_macro.c</td></tr></table>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen <p>Provides macros within Apache httpd runtime configuration files,
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen to ease the process of creating numerous similar configuration
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen blocks. When the server starts up, the macros are expanded using the
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen provided parameters, and the result is processed as along with the
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen rest of the configuration file.</p>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div id="quickview"><h3 class="directives">Directives</h3>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<li><img alt="" src="/images/down.gif" /> <a href="#macro"><Macro></a></li>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<li><img alt="" src="/images/down.gif" /> <a href="#undefmacro">UndefMacro</a></li>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<li><img alt="" src="/images/down.gif" /> <a href="#use">Use</a></li>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<li><img alt="" src="/images/down.gif" /> <a href="#usage">Usage</a></li>
d5e8240ee767cced65a45a2b9d590ca08b3d3859rbowen<li><img alt="" src="/images/down.gif" /> <a href="#tips">Tips</a></li>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>Macros are defined using <code class="directive"><Macro></code> blocks, which contain the portion of
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenyour configuration that needs to be repeated, complete with variables
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenfor those parts that will need to be substituted.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>For example, you might use a macro to define a <code class="directive"><VirtualHost></code> block, in order to define
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenmultiple similar virtual hosts:</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<Macro VHost $name $domain>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<VirtualHost *:80>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen ServerName $domain
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen ServerAlias www.$domain
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen>/VirtualHost>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen</Macro>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>Macro names are case-insensitive, like httpd configuration
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowendirectives. However, variable names are case sensitive.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>You would then invoke this macro several times to create virtual
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenUse VHost example example.com
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenUse VHost myhost hostname.org
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenUse VHost apache apache.org
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenUndefMacro VHost
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>At server startup time, each of these <code class="directive">Use</code>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drboweninvocations would be expanded into a full virtualhost, as
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowendescribed by the <code class="directive">Macro</code> definition.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>The <code class="directive">UndefMacro</code> directive is used so that later
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenmacros using the same variable names don't result in conflicting
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowendefinitions.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>A more elaborate version of this example may be seen below in the
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenExamples section.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>Parameter names should begin with a sigil such as <code>$</code>,
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<code>%</code>, or <code>@</code>, so that they are clearly
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenidentifiable, and also in order to help deail with interactions with
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenother directives, such as the core <code class="directive"><a href="/mod/core.html#define">Define</a></code> directive. Failure to do so will
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenresult in a warning. Nevertheless, you are encouraged to have a good
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenknowledge of your entire server configuration in order to avoid reusing
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenthe same variables in different scopes, which can cause confusion.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>Parameters prefixed with either <code>$</code> or <code>%</code> are
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowennot escaped. Parameters prefixes with <code>@</code> are escaped in
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>Avoid using a parameter which contains another parameter as a prefix,
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen(For example, <code>$win</code> and <code>$winter</code>) as this may
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowencause confusion at expression evaluation time. In the event of such
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenconfusion, the longest possible parameter name is used.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<p>If you want to use a value within another string, it is useful to
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowensurround the parameter in braces, to avoid confusion:</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<Macro DocRoot ${docroot}>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen</Macro>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<h2><a name="examples" id="examples">Examples</a></h2>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<p>A common usage of <code class="module"><a href="/mod/mod_macro.html">mod_macro</a></code> is for the creation of
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowendynamically-generated virtual hosts.</p>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen## Define a VHost Macro for repetitive configurations
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<Macro VHost $host $port $dir>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen Listen $port
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen <VirtualHost *:$port>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen ServerName $host
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen DocumentRoot $dir
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen # Public document root
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen <Directory $dir>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen Require all granted
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen </Directory>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen # limit access to intranet subdir.
5f42e12f1d9b59e2b18e7a7d55184d30dca8b067rbowen Require ip 10.0.0.0/8
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen </Directory>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen </VirtualHost>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen</Macro>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen## Use of VHost with different arguments.
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowenUse VHost www.example.fr 1234 /vhosts/example.fr/htdocs
6d92f6ca27b32822e9a78596f4ab561cd65b7016rbowen<p>It's recommended that you undefine a macro once you've used it. This
6d92f6ca27b32822e9a78596f4ab561cd65b7016rbowenavoids confusion in a complex configuration file where there may be
6d92f6ca27b32822e9a78596f4ab561cd65b7016rbowenconflicts in variable names.</p>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen<Macro DirGroup $dir $group>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen <Directory $dir>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen Require group $group
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen </Directory>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowen</Macro>
11a346d1a1cdd14cbc7b75e971fc22dc1358c28drbowenUndefMacro DirGroup
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div class="directive-section"><h2><a name="Macro" id="Macro"><Macro></a> <a name="macro" id="macro">Directive</a></h2>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a configuration file macro</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen <p>The <code class="directive">Macro</code> directive controls the definition of
cfbca4e518f4981f435e93e434f17271e6efc138rbowen a macro within the server runtime configuration files.
cfbca4e518f4981f435e93e434f17271e6efc138rbowen The first argument is the name of the macro.
cfbca4e518f4981f435e93e434f17271e6efc138rbowen Other arguments are parameters to the macro. It is good practice to prefix
cfbca4e518f4981f435e93e434f17271e6efc138rbowen parameter names with any of '<code>$%@</code>', and not macro names
cfbca4e518f4981f435e93e434f17271e6efc138rbowen with such characters.
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<Macro LocalAccessPolicy>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen</Macro>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<Macro RestrictedAccessPolicy $ipnumbers>
77a4b9c33b0e36baf1686869ff7a3ff514b91475rbowen Require ip $ipnumbers
cfbca4e518f4981f435e93e434f17271e6efc138rbowen</Macro>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<div class="directive-section"><h2><a name="UndefMacro" id="UndefMacro">UndefMacro</a> <a name="undefmacro" id="undefmacro">Directive</a></h2>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine a macro</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UndefMacro <var>name</var></code></td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen <p>The <code class="directive">UndefMacro</code> directive undefines a macro
cfbca4e518f4981f435e93e434f17271e6efc138rbowen which has been defined before hand.</p>
cfbca4e518f4981f435e93e434f17271e6efc138rbowenUndefMacro LocalAccessPolicy
cfbca4e518f4981f435e93e434f17271e6efc138rbowenUndefMacro RestrictedAccessPolicy
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<div class="directive-section"><h2><a name="Use" id="Use">Use</a> <a name="use" id="use">Directive</a></h2>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use a macro</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
9546947d8f7082fb4b70e1659feb5460502b73e4rbowen <p>The <code class="directive">Use</code> directive controls the use of a macro.
cfbca4e518f4981f435e93e434f17271e6efc138rbowen The specified macro is expanded. It must be given the same number of
cfbca4e518f4981f435e93e434f17271e6efc138rbowen arguments than in the macro definition. The provided values are
cfbca4e518f4981f435e93e434f17271e6efc138rbowen associated to their corresponding initial parameters and are substituted
cfbca4e518f4981f435e93e434f17271e6efc138rbowen before processing.</p>
e60187855fd0488f48f37e88acde742754308d39rbowenUse LocalAccessPolicy
e60187855fd0488f48f37e88acde742754308d39rbowenUse RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<p><span>Available Languages: </span><a href="/en/mod/mod_macro.html" title="English"> en </a> |
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<a href="/fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen</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>
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<script type="text/javascript"><!--//--><![CDATA[//><!--
cfbca4e518f4981f435e93e434f17271e6efc138rbowenvar comments_shortname = 'httpd';
cfbca4e518f4981f435e93e434f17271e6efc138rbowenvar comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_macro.html';
cfbca4e518f4981f435e93e434f17271e6efc138rbowen(function(w, d) {
cfbca4e518f4981f435e93e434f17271e6efc138rbowen if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
cfbca4e518f4981f435e93e434f17271e6efc138rbowen d.write('<div id="comments_thread"><\/div>');
cfbca4e518f4981f435e93e434f17271e6efc138rbowen var s = d.createElement('script');
cfbca4e518f4981f435e93e434f17271e6efc138rbowen s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
cfbca4e518f4981f435e93e434f17271e6efc138rbowen (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
cfbca4e518f4981f435e93e434f17271e6efc138rbowen d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
cfbca4e518f4981f435e93e434f17271e6efc138rbowen})(window, document);
cfbca4e518f4981f435e93e434f17271e6efc138rbowen<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>
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></div><script type="text/javascript"><!--//--><![CDATA[//><!--
cfbca4e518f4981f435e93e434f17271e6efc138rbowenif (typeof(prettyPrint) !== 'undefined') {
cfbca4e518f4981f435e93e434f17271e6efc138rbowen prettyPrint();