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

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_macro.xml.meta">
  24
  25 <name>mod_macro</name>
  26 <description>Provides macros within apache httpd runtime configuration files</description>
  27 <status>Base</status>
  28 <sourcefile>mod_macro.c</sourcefile>
  29 <identifier>macro_module</identifier>
  30
  31 <summary>
  32
  33     <p>Provides macros within Apache httpd runtime configuration files,
  34     to ease the process of creating numerous similar configuration
  35     blocks. When the server starts up, the macros are expanded using the
  36     provided parameters, and the result is processed as along with the
  37     rest of the configuration file.</p>
  38
  39 </summary>
  40
  41 <section id="usage"><title>Usage</title>
  42
  43 <p>Macros are defined using <directive module="mod_macro"
  44 type="section">Macro</directive> blocks, which contain the portion of
  45 your configuration that needs to be repeated, complete with variables
  46 for those parts that will need to be substituted.</p>
  47
  48 <p>For example, you might use a macro to define a <directive module="core"
  49 type="section">VirtualHost</directive> block, in order to define
  50 multiple similar virtual hosts:</p>
  51
  52 <highlight language="config">
  53 &lt;Macro VHost $name $domain&gt;
  54 &lt;VirtualHost *:80&gt;
  55     ServerName $domain
  56     ServerAlias www.$domain
  57
  58     DocumentRoot "/var/www/vhosts/$name"
  59     ErrorLog "/var/log/httpd/$name.error_log"
  60     CustomLog "/var/log/httpd/$name.access_log" combined
  61 &lt;/VirtualHost&gt;
  62 &lt;/Macro&gt;
  63 </highlight>
  64
  65 <p>Macro names are case-insensitive, like httpd configuration
  66 directives. However, variable names are case sensitive.</p>
  67
  68 <p>You would then invoke this macro several times to create virtual
  69 hosts:</p>
  70
  71 <highlight language="config">
  72 Use VHost example example.com
  73 Use VHost myhost hostname.org
  74 Use VHost apache apache.org
  75
  76 UndefMacro VHost
  77 </highlight>
  78
  79 <p>At server startup time, each of these <directive module="mod_macro">Use</directive>
  80 invocations would be expanded into a full virtualhost, as
  81 described by the <directive module="mod_macro" type="section">Macro</directive>
  82 definition.</p>
  83
  84 <p>The <directive module="mod_macro">UndefMacro</directive> directive is
  85 used so that later macros using the same variable names don't result in
  86 conflicting definitions.</p>
  87
  88 <p>A more elaborate version of this example may be seen below in the
  89 Examples section.</p>
  90
  91 </section>
  92
  93 <section id="tips"><title>Tips</title>
  94
  95 <p>Parameter names should begin with a sigil such as <code>$</code>,
  96 <code>%</code>, or <code>@</code>, so that they are clearly
  97 identifiable, and also in order to help deal with interactions with
  98 other directives, such as the core <directive
  99 module="core">Define</directive> directive. Failure to do so will
 100 result in a warning. Nevertheless, you are encouraged to have a good
 101 knowledge of your entire server configuration in order to avoid reusing
 102 the same variables in different scopes, which can cause confusion.</p>
 103
 104 <p>Parameters prefixed with either <code>$</code> or <code>%</code> are
 105 not escaped. Parameters prefixes with <code>@</code> are escaped in
 106 quotes.</p>
 107
 108 <p>Avoid using a parameter which contains another parameter as a prefix,
 109 (For example, <code>$win</code> and <code>$winter</code>) as this may
 110 cause confusion at expression evaluation time. In the event of such
 111 confusion, the longest possible parameter name is used.</p>
 112
 113 <p>If you want to use a value within another string, it is useful to
 114 surround the parameter in braces, to avoid confusion:</p>
 115
 116 <highlight language="config">
 117 &lt;Macro DocRoot ${docroot}&gt;
 118     DocumentRoot "/var/www/${docroot}/htdocs"
 119 &lt;/Macro&gt;
 120 </highlight>
 121
 122 </section>
 123
 124 <section id="examples">
 125 <title>Examples</title>
 126
 127 <section>
 128 <title>Virtual Host Definition</title>
 129
 130 <p>A common usage of <module>mod_macro</module> is for the creation of
 131 dynamically-generated virtual hosts.</p>
 132
 133 <highlight language="config">
 134 ## Define a VHost Macro for repetitive configurations
 135
 136 &lt;Macro VHost $host $port $dir&gt;
 137   Listen $port
 138   &lt;VirtualHost *:$port&gt;
 139
 140     ServerName $host
 141     DocumentRoot "$dir"
 142
 143     # Public document root
 144     &lt;Directory "$dir"&gt;
 145         Require all granted
 146     &lt;/Directory&gt;
 147
 148     # limit access to intranet subdir.
 149     &lt;Directory "$dir/intranet"&gt;
 150       Require ip 10.0.0.0/8
 151     &lt;/Directory&gt;
 152   &lt;/VirtualHost&gt;
 153 &lt;/Macro&gt;
 154
 155 ## Use of VHost with different arguments.
 156
 157 Use VHost www.apache.org 80 /vhosts/apache/htdocs
 158 Use VHost example.org 8080 /vhosts/example/htdocs
 159 Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs
 160 </highlight>
 161 </section> <!-- Vhosts -->
 162
 163 <section>
 164 <title>Removal of a macro definition</title>
 165
 166 <p>It's recommended that you undefine a macro once you've used it. This
 167 avoids confusion in a complex configuration file where there may be
 168 conflicts in variable names.</p>
 169
 170 <highlight language="config">
 171 &lt;Macro DirGroup $dir $group&gt;
 172   &lt;Directory "$dir"&gt;
 173     Require group $group
 174   &lt;/Directory&gt;
 175 &lt;/Macro&gt;
 176
 177 Use DirGroup /www/apache/private private
 178 Use DirGroup /www/apache/server  admin
 179
 180 UndefMacro DirGroup
 181 </highlight>
 182
 183 </section> <!-- UndefMacro -->
 184
 185 </section> <!-- Example -->
 186
 187 <!-- Macro -->
 188 <directivesynopsis type="section">
 189 <name>Macro</name>
 190 <description>Define a configuration file macro</description>
 191 <syntax>
 192 &lt;Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]&gt;
 193 ... &lt;/Macro&gt;</syntax>
 194 <contextlist>
 195 <context>server config</context>
 196 <context>virtual host</context>
 197 <context>directory</context>
 198 </contextlist>
 199 <override>All</override>
 200
 201 <usage>
 202     <p>The <directive type="section">Macro</directive> directive controls the
 203     definition of a macro within the server runtime configuration files.
 204     The first argument is the name of the macro.
 205     Other arguments are parameters to the macro. It is good practice to prefix
 206     parameter names with any of '<code>$%@</code>', and not macro names
 207     with such characters.
 208     </p>
 209
 210     <highlight language="config">
 211 &lt;Macro LocalAccessPolicy&gt;
 212     Require ip 10.2.16.0/24
 213 &lt;/Macro&gt;
 214
 215 &lt;Macro RestrictedAccessPolicy $ipnumbers&gt;
 216     Require ip $ipnumbers
 217 &lt;/Macro&gt;
 218     </highlight>
 219 </usage>
 220 </directivesynopsis>
 221
 222 <!-- Use -->
 223 <directivesynopsis>
 224 <name>Use</name>
 225 <description>Use a macro</description>
 226 <syntax>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
 227 </syntax>
 228 <contextlist>
 229 <context>server config</context>
 230 <context>virtual host</context>
 231 <context>directory</context>
 232 </contextlist>
 233 <override>All</override>
 234
 235 <usage>
 236     <p>The <directive>Use</directive> directive controls the use of a macro.
 237     The specified macro is expanded. It must be given the same number of
 238     arguments as in the  macro definition. The provided values are
 239     associated to their corresponding initial parameters and are substituted
 240     before processing.</p>
 241
 242     <highlight language="config">
 243 Use LocalAccessPolicy
 244 ...
 245 Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
 246     </highlight>
 247
 248     <p>is equivalent, with the macros defined above, to:</p>
 249
 250     <highlight language="config">
 251 Require ip 10.2.16.0/24
 252 ...
 253 Require ip 192.54.172.0/24 192.54.148.0/24
 254     </highlight>
 255 </usage>
 256
 257 </directivesynopsis>
 258
 259 <!-- UndefMacro -->
 260 <directivesynopsis>
 261 <name>UndefMacro</name>
 262 <description>Undefine a macro</description>
 263
 264 <syntax>UndefMacro <var>name</var></syntax>
 265 <contextlist>
 266 <context>server config</context>
 267 <context>virtual host</context>
 268 <context>directory</context>
 269 </contextlist>
 270 <override>All</override>
 271
 272 <usage>
 273     <p>The <directive>UndefMacro</directive> directive undefines a macro
 274     which has been defined before hand.</p>
 275
 276     <highlight language="config">
 277 UndefMacro LocalAccessPolicy
 278 UndefMacro RestrictedAccessPolicy
 279     </highlight>
 280 </usage>
 281 </directivesynopsis>
 282
 283 <!-- MacroIgnoreEmptyArg -->
 284 <directivesynopsis>
 285 <name>MacroIgnoreEmptyArgs</name>
 286 <description>Ignore warnings, and does not log, about empty Macro argument(s)</description>
 287
 288 <syntax>MacroIgnoreEmptyArgs</syntax>
 289 <contextlist>
 290 <context>server config</context>
 291 <context>virtual host</context>
 292 <context>directory</context>
 293 </contextlist>
 294 <override>All</override>
 295
 296 </directivesynopsis>
 297
 298 <!-- MacroIgnoreBadNesting -->
 299 <directivesynopsis>
 300 <name>MacroIgnoreBadNesting</name>
 301 <description>Ignore warnings, and does not log, about bad nesting of Macros</description>
 302
 303 <syntax>MacroIgnoreBadNesting</syntax>
 304 <contextlist>
 305 <context>server config</context>
 306 <context>virtual host</context>
 307 <context>directory</context>
 308 </contextlist>
 309 <override>All</override>
 310
 311 </directivesynopsis>
 312
 313 </modulesynopsis>