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/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>
  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>Provides macros within Apache httpd runtime configuration files,
  38     to ease the process of creating numerous similar configuration
  39     blocks. When the server starts up, the macros are expanded using the
  40     provided parameters, and the result is processed as along with the
  41     rest of the configuration file.</p>
  42
  43 </div>
  44 <div id="quickview"><h3 class="directives">Directives</h3>
  45 <ul id="toc">
  46 <li><img alt="" src="../images/down.gif" /> <a href="#macro">&lt;Macro&gt;</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#undefmacro">UndefMacro</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#use">Use</a></li>
  49 </ul>
  50 <h3>Topics</h3>
  51 <ul id="topics">
  52 <li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#tips">Tips</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  55 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  56 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  57 <div class="section">
  58 <h2><a name="usage" id="usage">Usage</a></h2>
  59
  60 <p>Macros are defined using <code class="directive">&lt;Macro&gt;</code> blocks, which contain the portion of
  61 your configuration that needs to be repeated, complete with variables
  62 for those parts that will need to be substituted.</p>
  63
  64 <p>For example,  you might use a macro to define a <code class="directive">&lt;VirtualHost&gt;</code> block, in order to define
  65 multiple similar virtual hosts:</p>
  66
  67 <pre class="prettyprint lang-config">
  68 &lt;Macro VHost $name $domain&gt;
  69 &lt;VirtualHost *:80&gt;
  70     ServerName $domain
  71     ServerAlias www.$domain
  72
  73     DocumentRoot /var/www/vhosts/$name
  74     ErrorLog /var/log/httpd/$name.error_log
  75     CustomLog /var/log/httpd/$name.access_log combined
  76 &gt;/VirtualHost&gt;
  77 &lt;/Macro&gt;
  78 </pre>
  79
  80
  81 <p>Macro names are case-insensitive, like httpd configuration
  82 directives. However, variable names are case sensitive.</p>
  83
  84 <p>You would then invoke this macro several times to create virtual
  85 hosts:</p>
  86
  87 <pre class="prettyprint lang-config">
  88 Use VHost example example.com
  89 Use VHost myhost hostname.org
  90 Use VHost apache apache.org
  91
  92 UndefMacro VHost
  93 </pre>
  94
  95
  96 <p>At server startup time, each of these <code class="directive">Use</code>
  97 invocations would be expanded into a full virtualhost, as
  98 described by the <code class="directive">Macro</code> definition.</p>
  99
 100 <p>The <code class="directive">UndefMacro</code> directive is used so that later
 101 macros using the same variable names don't result in conflicting
 102 definitions.</p>
 103
 104 <p>A more elaborate version of this example may be seen below in the
 105 Examples section.</p>
 106
 107 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 108 <div class="section">
 109 <h2><a name="tips" id="tips">Tips</a></h2>
 110
 111 <p>Parameter names should begin with a sigil such as <code>$</code>,
 112 <code>%</code>, or <code>@</code>, so that they are clearly
 113 identifiable, and also in order to help deail with interactions with
 114 other directives, such as the core <code class="directive"><a href="../mod/core.html#define">Define</a></code> directive. Failure to do so will
 115 result in a warning. Nevertheless, you are encouraged to have a good
 116 knowledge of your entire server configuration in order to avoid reusing
 117 the same variables in different scopes, which can cause confusion.</p>
 118
 119 <p>Parameters prefixed with either <code>$</code> or <code>%</code> are
 120 not escaped. Parameters prefixes with <code>@</code> are escaped in
 121 quotes.</p>
 122
 123 <p>Avoid using a parameter which contains another parameter as a prefix,
 124 (For example, <code>$win</code> and <code>$winter</code>) as this may
 125 cause confusion at expression evaluation time. In the event of such
 126 confusion, the longest possible parameter name is used.</p>
 127
 128 <p>If you want to use a value within another string, it is useful to
 129 surround the parameter in braces, to avoid confusion:</p>
 130
 131 <pre class="prettyprint lang-config">
 132 &lt;Macro DocRoot ${docroot}&gt;
 133     DocumentRoot /var/www/${docroot}/htdocs
 134 &lt;/Macro&gt;
 135 </pre>
 136
 137
 138 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 139 <div class="section">
 140 <h2><a name="examples" id="examples">Examples</a></h2>
 141
 142
 143 <h3>Virtual Host Definition</h3>
 144
 145
 146 <p>A common usage of <code class="module"><a href="../mod/mod_macro.html">mod_macro</a></code> is for the creation of
 147 dynamically-generated virtual hosts.</p>
 148
 149 <pre class="prettyprint lang-config">
 150 ## Define a VHost Macro for repetitive configurations
 151
 152 &lt;Macro VHost $host $port $dir&gt;
 153   Listen $port
 154   &lt;VirtualHost *:$port&gt;
 155
 156     ServerName $host
 157     DocumentRoot $dir
 158
 159     # Public document root
 160     &lt;Directory $dir&gt;
 161         Require all granted
 162     &lt;/Directory&gt;
 163
 164     # limit access to intranet subdir.
 165     &lt;Directory $dir/intranet&gt;
 166       Require ip 10.0.0.0/8
 167     &lt;/Directory&gt;
 168   &lt;/VirtualHost&gt;
 169 &lt;/Macro&gt;
 170
 171 ## Use of VHost with different arguments.
 172
 173 Use VHost www.apache.org 80 /vhosts/apache/htdocs
 174 Use VHost example.org 8080 /vhosts/example/htdocs
 175 Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs
 176 </pre>
 177
 178
 179
 180 <h3>Removal of a macro definition</h3>
 181
 182
 183 <p>It's recommended that you undefine a macro once you've used it. This
 184 avoids confusion in a complex configuration file where there may be
 185 conflicts in variable names.</p>
 186
 187 <pre class="prettyprint lang-config">
 188 &lt;Macro DirGroup $dir $group&gt;
 189   &lt;Directory $dir&gt;
 190     Require group $group
 191   &lt;/Directory&gt;
 192 &lt;/Macro&gt;
 193
 194 Use DirGroup /www/apache/private private
 195 Use DirGroup /www/apache/server  admin
 196
 197 UndefMacro DirGroup
 198 </pre>
 199
 200
 201
 202
 203 </div>
 204 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 205 <div class="directive-section"><h2><a name="Macro" id="Macro">&lt;Macro&gt;</a> <a name="macro" id="macro">Directive</a></h2>
 206 <table class="directive">
 207 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a configuration file macro</td></tr>
 208 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>
 209 &lt;Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]&gt;
 210 ... &lt;/Macro&gt;</code></td></tr>
 211 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 212 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 213 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
 214 </table>
 215     <p>The <code class="directive">Macro</code> directive controls the definition of
 216     a macro within the server runtime configuration files.
 217     The first argument is the name of the macro.
 218     Other arguments are parameters to the macro. It is good practice to prefix
 219     parameter names with any of '<code>$%@</code>', and not macro names
 220     with such characters.
 221     </p>
 222
 223     <pre class="prettyprint lang-config">
 224 &lt;Macro LocalAccessPolicy&gt;
 225     Require ip 10.2.16.0/24
 226 &lt;/Macro&gt;
 227
 228 &lt;Macro RestrictedAccessPolicy $ipnumbers&gt;
 229     Require ip $ipnumbers
 230 &lt;/Macro&gt;
 231     </pre>
 232
 233
 234 </div>
 235 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 236 <div class="directive-section"><h2><a name="UndefMacro" id="UndefMacro">UndefMacro</a> <a name="undefmacro" id="undefmacro">Directive</a></h2>
 237 <table class="directive">
 238 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine a macro</td></tr>
 239 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UndefMacro <var>name</var></code></td></tr>
 240 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 241 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 242 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
 243 </table>
 244     <p>The <code class="directive">UndefMacro</code> directive undefines a macro
 245     which has been defined before hand.</p>
 246
 247     <pre class="prettyprint lang-config">
 248 UndefMacro LocalAccessPolicy
 249 UndefMacro RestrictedAccessPolicy
 250     </pre>
 251
 252
 253 </div>
 254 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 255 <div class="directive-section"><h2><a name="Use" id="Use">Use</a> <a name="use" id="use">Directive</a></h2>
 256 <table class="directive">
 257 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Use a macro</td></tr>
 258 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
 259 </code></td></tr>
 260 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
 261 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 262 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_macro</td></tr>
 263 </table>
 264     <p>The <code class="directive">Use</code> directive controls the use of a macro.
 265     The specified macro is expanded. It must be given the same number of
 266     arguments than in the  macro definition. The provided values are
 267     associated to their corresponding initial parameters and are substituted
 268     before processing.</p>
 269
 270     <pre class="prettyprint lang-config">
 271 Use LocalAccessPolicy
 272 ...
 273 Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
 274     </pre>
 275
 276
 277     <p>is equivalent, with the macros defined above, to:</p>
 278
 279     <pre class="prettyprint lang-config">
 280 Require ip 10.2.16.0/24
 281 ...
 282 Require ip 192.54.172.0/24 192.54.148.0/24
 283     </pre>
 284
 285
 286 </div>
 287 </div>
 288 <div class="bottomlang">
 289 <p><span>Available Languages: </span><a href="../en/mod/mod_macro.html" title="English">&nbsp;en&nbsp;</a> |
 290 <a href="../fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 291 </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>
 292 <script type="text/javascript"><!--//--><![CDATA[//><!--
 293 var comments_shortname = 'httpd';
 294 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_macro.html';
 295 (function(w, d) {
 296     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 297         d.write('<div id="comments_thread"><\/div>');
 298         var s = d.createElement('script');
 299         s.type = 'text/javascript';
 300         s.async = true;
 301         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 302         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 303     }
 304     else {
 305         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 306     }
 307 })(window, document);
 308 //--><!]]></script></div><div id="footer">
 309 <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>
 310 <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[//><!--
 311 if (typeof(prettyPrint) !== 'undefined') {
 312     prettyPrint();
 313 }
 314 //--><!]]></script>
 315 </body></html>