granicus.if.org Git - apache/blob - docs/manual/mod/mod_macro.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_macro - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <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" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body>
  17 <div id="page-header">
  18 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.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>
  19 <p class="apache">Apache HTTP Server Version 2.5</p>
  20 <img alt="" src="../images/feather.gif" /></div>
  21 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  22 <div id="path">
  23 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  24 <div id="page-content">
  25 <div id="preamble"><h1>Apache Module mod_macro</h1>
  26 <div class="toplang">
  27 <p><span>Available Languages: </span><a href="../en/mod/mod_macro.html" title="English">&nbsp;en&nbsp;</a> |
  28 <a href="../fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  29 </div>
  30 <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>
  31 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
  32 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>macro_module</td></tr>
  33 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_macro.c</td></tr></table>
  34 <h3>Summary</h3>
  35
  36
  37     <p>This modules provides macros within apache httpd runtime configuration files.
  38     These macros may have parameters. They are expanded when used (parameters are
  39     substituted by their values given as an argument), and the result is
  40     processed normally.</p>
  41 </div>
  42 <div id="quickview"><h3 class="directives">Directives</h3>
  43 <ul id="toc">
  44 <li><img alt="" src="../images/down.gif" /> <a href="#macro">&lt;Macro&gt;</a></li>
  45 <li><img alt="" src="../images/down.gif" /> <a href="#undefmacro">UndefMacro</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#use">Use</a></li>
  47 </ul>
  48 <h3>Topics</h3>
  49 <ul id="topics">
  50 <li><img alt="" src="../images/down.gif" /> <a href="#features">Features</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  52 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  53 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  54 <div class="section">
  55 <h2><a name="features" id="features">Features</a></h2>
  56
  57 <p>Definition of a macro:</p>
  58
  59     <ul>
  60     <li> macro definition within a <code class="directive">&lt;Macro&gt;</code> section, following
  61          the httpd configuration style.</li>
  62     <li> user defined names for the macro and its parameters.</li>
  63     <li> macro names are case-insensitive, like httpd directives.</li>
  64     <li> macro parameter names are case sensitive.</li>
  65     <li> macro parameters must have distinct names.</li>
  66     <li> error on empty parameter names.</li>
  67     <li> redefining a macro generates a warning.</li>
  68     <li> macro definitions can be nested... (but what for?)</li>
  69     <li> warn about unused macro parameters.</li>
  70     <li> warn about macro parameter names which prefix one another.</li>
  71     <li> warn if a parameter is not prefixed by any of '<code>$%@</code>'
  72          (good practice).</li>
  73     <li> the available prefixes help deal with interactions with other
  74          directives such as <code class="directive"><a href="../mod/core.html#define">Define</a></code>.</li>
  75     <li> tip: it may be useful to define a macro parameter with surrounding
  76          braces, say <code>${foo}</code> so that the name can appear with
  77          surrounding characters such as <code>bla${foo}bla</code>.</li>
  78     <li> warn about empty macro contents.</li>
  79     <li> warns if sections are not properly nested within a macro.
  80          (if it is detected so).</li>
  81     <li> the lexical scope of macro parameters is restricted to the macro text,
  82          it is not forwarded to includes for instance.</li>
  83     <li> arbitrary contents in macros.
  84          <p>It means you can put perl sections or whatever you like in a macro.
  85          No assumption is made about the lexical structure (quotes, spaces or
  86          whatever) within the macro contents but to expect a set of
  87          backslash-continued independent lines.</p></li>
  88     </ul>
  89
  90 <p>Use of a macro:</p>
  91
  92     <ul>
  93     <li> number of arguments must match the definition.</li>
  94     <li> all occurences of macro parameters are substituted by their values.</li>
  95     <li> in case of conflicts, the longest parameter name is chosen.</li>
  96     <li> macro expansion recursion is detected and stopped (error).</li>
  97     <li> warn about empty arguments when used.</li>
  98     <li> on errors, try to describe precisely where the error occured.</li>
  99     <li> <code>$</code> and <code>%</code>-prefixed parameters are not
 100           escaped.</li>
 101     <li> <code>@</code>-prefixed parameters are escaped in quotes.</li>
 102     </ul>
 103
 104 <p>Removal of a macro definition:</p>
 105
 106    <ul>
 107    <li> the macro must be already defined.</li>
 108    </ul>
 109
 110 <pre class="prettyprint lang-config">
 111 &lt;Macro DirGroup $dir $group&gt;
 112   &lt;Directory $dir&gt;
 113     require group $group
 114   &lt;/Directory&gt;
 115 &lt;/Macro&gt;
 116
 117 Use DirGroup /www/apache/private private
 118 Use DirGroup /www/apache/server  admin
 119
 120 UndefMacro DirGroup
 121 </pre>
 122
 123
 124 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 125 <div class="section">
 126 <h2><a name="examples" id="examples">Examples</a></h2>
 127
 128 <p>A common usage of <code class="module"><a href="../mod/mod_macro.html">mod_macro</a></code> is for the creation of
 129 dynamically-generated virtual hosts.</p>
 130
 131 <pre class="prettyprint lang-config">
 132 ## Define a VHost Macro for repetitive configurations
 133
 134 &lt;Macro VHost $host $port $dir&gt;
 135   Listen $port
 136   &lt;VirtualHost *:$port&gt;
 137
 138     ServerName $host
 139     DocumentRoot $dir
 140
 141     &lt;Directory $dir&gt;
 142       # do something here...
 143     &lt;/Directory&gt;
 144
 145     # limit access to intranet subdir.
 146     &lt;Directory $dir/intranet&gt;
 147       order deny,allow
 148       deny from all
 149       allow from 10.0.0.0/8
 150     &lt;/Directory&gt;
 151   &lt;/VirtualHost&gt;
 152 &lt;/Macro&gt;
 153
 154 ## Use of VHost with different arguments.
 155
 156 Use VHost www.apache.org 80 /vhosts/apache/htdocs
 157 Use VHost example.org 8080 /vhosts/example/htdocs
 158 Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs
 159 </pre>
 160
 161
 162 </div>
 163 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 164 <div class="directive-section"><h2><a name="Macro" id="Macro">&lt;Macro&gt;</a> <a name="macro" id="macro">Directive</a></h2>
 165 <table class="directive">
 166 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a configuration file macro</td></tr>
 167 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>
 168 &lt;Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]&gt;
 169 ... &lt;/Macro&gt;</code></td></tr>
 170 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 171 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 172 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
 173 </table>
 174     <p>The <code class="directive">Macro</code> directive controls the definition of
 175     a macro within the server runtime configuration files.
 176     The first argument is the name of the macro.
 177     Other arguments are parameters to the macro. It is good practice to prefix
 178     parameter names with any of '<code>$%@</code>', and not macro names
 179     with such characters.
 180     </p>
 181
 182     <pre class="prettyprint lang-config">
 183 &lt;Macro LocalAccessPolicy&gt;
 184     Require ip 10.2.16.0/24
 185 &lt;/Macro&gt;
 186
 187 &lt;Macro RestrictedAccessPolicy $ipnumbers&gt;
 188     Require ip $ipnumbers
 189 &lt;/Macro&gt;
 190     </pre>
 191
 192
 193 </div>
 194 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 195 <div class="directive-section"><h2><a name="UndefMacro" id="UndefMacro">UndefMacro</a> <a name="undefmacro" id="undefmacro">Directive</a></h2>
 196 <table class="directive">
 197 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine a macro</td></tr>
 198 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UndefMacro <var>name</var></code></td></tr>
 199 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 200 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 201 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
 202 </table>
 203     <p>The <code class="directive">UndefMacro</code> directive undefines a macro
 204     which has been defined before hand.</p>
 205
 206     <pre class="prettyprint lang-config">
 207 UndefMacro LocalAccessPolicy
 208 UndefMacro RestrictedAccessPolicy
 209     </pre>
 210
 211
 212 </div>
 213 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 214 <div class="directive-section"><h2><a name="Use" id="Use">Use</a> <a name="use" id="use">Directive</a></h2>
 215 <table class="directive">
 216 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use a macro</td></tr>
 217 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
 218 </code></td></tr>
 219 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 220 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 221 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
 222 </table>
 223     <p>The <code class="directive">Use</code> directive controls the use of a macro.
 224     The specified macro is expanded. It must be given the same number of
 225     arguments than in the  macro definition. The provided values are
 226     associated to their corresponding initial parameters and are substituted
 227     before processing.</p>
 228
 229     <pre class="prettyprint lang-config">
 230 Use LocalAccessPolicy
 231 ...
 232 Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
 233     </pre>
 234
 235
 236     <p>is equivalent, with the macros defined above, to:</p>
 237
 238     <pre class="prettyprint lang-config">
 239 Require ip 10.2.16.0/24
 240 ...
 241 Require ip 192.54.172.0/24 192.54.148.0/24
 242     </pre>
 243
 244
 245 </div>
 246 </div>
 247 <div class="bottomlang">
 248 <p><span>Available Languages: </span><a href="../en/mod/mod_macro.html" title="English">&nbsp;en&nbsp;</a> |
 249 <a href="../fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 250 </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&amp;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>
 251 <script type="text/javascript"><!--//--><![CDATA[//><!--
 252 var comments_shortname = 'httpd';
 253 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_macro.html';
 254 (function(w, d) {
 255     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 256         d.write('<div id="comments_thread"><\/div>');
 257         var s = d.createElement('script');
 258         s.type = 'text/javascript';
 259         s.async = true;
 260         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 261         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 262     }
 263     else {
 264         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 265     }
 266 })(window, document);
 267 //--><!]]></script></div><div id="footer">
 268 <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>
 269 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.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[//><!--
 270 if (typeof(prettyPrint) !== 'undefined') {
 271     prettyPrint();
 272 }
 273 //--><!]]></script>
 274 </body></html>