| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_macro.xml.meta"> |
| |
| <name>mod_macro</name> |
| <description>Provides macros within apache httpd runtime configuration files</description> |
| <status>Base</status> |
| <sourcefile>mod_macro.c</sourcefile> |
| <identifier>macro_module</identifier> |
| <compatibility>Available in httpd 2.4.5 and later</compatibility> |
| |
| <summary> |
| |
| <p>Provides macros within Apache httpd runtime configuration files, |
| to ease the process of creating numerous similar configuration |
| blocks. When the server starts up, the macros are expanded using the |
| provided parameters, and the result is processed as along with the |
| rest of the configuration file.</p> |
| |
| </summary> |
| |
| <section id="usage"><title>Usage</title> |
| |
| <p>Macros are defined using <directive module="mod_macro" |
| type="section">Macro</directive> blocks, which contain the portion of |
| your configuration that needs to be repeated, complete with variables |
| for those parts that will need to be substituted.</p> |
| |
| <p>For example, you might use a macro to define a <directive module="core" |
| type="section">VirtualHost</directive> block, in order to define |
| multiple similar virtual hosts:</p> |
| |
| <highlight language="config"> |
| <Macro VHost $name $domain> |
| <VirtualHost *:80> |
| ServerName $domain |
| ServerAlias www.$domain |
| |
| DocumentRoot "/var/www/vhosts/$name" |
| ErrorLog "/var/log/httpd/$name.error_log" |
| CustomLog "/var/log/httpd/$name.access_log" combined |
| </VirtualHost> |
| </Macro> |
| </highlight> |
| |
| <p>Macro names are case-insensitive, like httpd configuration |
| directives. However, variable names are case sensitive.</p> |
| |
| <p>You would then invoke this macro several times to create virtual |
| hosts:</p> |
| |
| <highlight language="config"> |
| Use VHost example example.com |
| Use VHost myhost hostname.org |
| Use VHost apache apache.org |
| |
| UndefMacro VHost |
| </highlight> |
| |
| <p>At server startup time, each of these <directive module="mod_macro">Use</directive> |
| invocations would be expanded into a full virtualhost, as |
| described by the <directive module="mod_macro" type="section">Macro</directive> |
| definition.</p> |
| |
| <p>The <directive module="mod_macro">UndefMacro</directive> directive is |
| used so that later macros using the same variable names don't result in |
| conflicting definitions.</p> |
| |
| <p>A more elaborate version of this example may be seen below in the |
| Examples section.</p> |
| |
| </section> |
| |
| <section id="tips"><title>Tips</title> |
| |
| <p>Parameter names should begin with a sigil such as <code>$</code>, |
| <code>%</code>, or <code>@</code>, so that they are clearly |
| identifiable, and also in order to help deal with interactions with |
| other directives, such as the core <directive |
| module="core">Define</directive> directive. Failure to do so will |
| result in a warning. Nevertheless, you are encouraged to have a good |
| knowledge of your entire server configuration in order to avoid reusing |
| the same variables in different scopes, which can cause confusion.</p> |
| |
| <p>Parameters prefixed with either <code>$</code> or <code>%</code> are |
| not escaped. Parameters prefixes with <code>@</code> are escaped in |
| quotes.</p> |
| |
| <p>Avoid using a parameter which contains another parameter as a prefix, |
| (For example, <code>$win</code> and <code>$winter</code>) as this may |
| cause confusion at expression evaluation time. In the event of such |
| confusion, the longest possible parameter name is used.</p> |
| |
| <p>If you want to use a value within another string, it is useful to |
| surround the parameter in braces, to avoid confusion:</p> |
| |
| <highlight language="config"> |
| <Macro DocRoot ${docroot}> |
| DocumentRoot "/var/www/${docroot}/htdocs" |
| </Macro> |
| </highlight> |
| |
| </section> |
| |
| <section id="examples"> |
| <title>Examples</title> |
| |
| <section> |
| <title>Virtual Host Definition</title> |
| |
| <p>A common usage of <module>mod_macro</module> is for the creation of |
| dynamically-generated virtual hosts.</p> |
| |
| <highlight language="config"> |
| ## Define a VHost Macro for repetitive configurations |
| |
| <Macro VHost $host $port $dir> |
| Listen $port |
| <VirtualHost *:$port> |
| |
| ServerName $host |
| DocumentRoot "$dir" |
| |
| # Public document root |
| <Directory "$dir"> |
| Require all granted |
| </Directory> |
| |
| # limit access to intranet subdir. |
| <Directory "$dir/intranet"> |
| Require ip 10.0.0.0/8 |
| </Directory> |
| </VirtualHost> |
| </Macro> |
| |
| ## Use of VHost with different arguments. |
| |
| Use VHost www.apache.org 80 /vhosts/apache/htdocs |
| Use VHost example.org 8080 /vhosts/example/htdocs |
| Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs |
| </highlight> |
| </section> <!-- Vhosts --> |
| |
| <section> |
| <title>Removal of a macro definition</title> |
| |
| <p>It's recommended that you undefine a macro once you've used it. This |
| avoids confusion in a complex configuration file where there may be |
| conflicts in variable names.</p> |
| |
| <highlight language="config"> |
| <Macro DirGroup $dir $group> |
| <Directory "$dir"> |
| Require group $group |
| </Directory> |
| </Macro> |
| |
| Use DirGroup /www/apache/private private |
| Use DirGroup /www/apache/server admin |
| |
| UndefMacro DirGroup |
| </highlight> |
| |
| </section> <!-- UndefMacro --> |
| |
| </section> <!-- Example --> |
| |
| <!-- Macro --> |
| <directivesynopsis type="section"> |
| <name>Macro</name> |
| <description>Define a configuration file macro</description> |
| <syntax> |
| <Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]> |
| ... </Macro></syntax> |
| <contextlist> |
| <context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>The <directive type="section">Macro</directive> directive controls the |
| definition of a macro within the server runtime configuration files. |
| The first argument is the name of the macro. |
| Other arguments are parameters to the macro. It is good practice to prefix |
| parameter names with any of '<code>$%@</code>', and not macro names |
| with such characters. |
| </p> |
| |
| <highlight language="config"> |
| <Macro LocalAccessPolicy> |
| Require ip 10.2.16.0/24 |
| </Macro> |
| |
| <Macro RestrictedAccessPolicy $ipnumbers> |
| Require ip $ipnumbers |
| </Macro> |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <!-- Use --> |
| <directivesynopsis> |
| <name>Use</name> |
| <description>Use a macro</description> |
| <syntax>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>] |
| </syntax> |
| <contextlist> |
| <context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>The <directive>Use</directive> directive controls the use of a macro. |
| The specified macro is expanded. It must be given the same number of |
| arguments as in the macro definition. The provided values are |
| associated to their corresponding initial parameters and are substituted |
| before processing.</p> |
| |
| <highlight language="config"> |
| Use LocalAccessPolicy |
| ... |
| Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24" |
| </highlight> |
| |
| <p>is equivalent, with the macros defined above, to:</p> |
| |
| <highlight language="config"> |
| Require ip 10.2.16.0/24 |
| ... |
| Require ip 192.54.172.0/24 192.54.148.0/24 |
| </highlight> |
| </usage> |
| |
| </directivesynopsis> |
| |
| <!-- UndefMacro --> |
| <directivesynopsis> |
| <name>UndefMacro</name> |
| <description>Undefine a macro</description> |
| |
| <syntax>UndefMacro <var>name</var></syntax> |
| <contextlist> |
| <context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <override>All</override> |
| |
| <usage> |
| <p>The <directive>UndefMacro</directive> directive undefines a macro |
| which has been defined before hand.</p> |
| |
| <highlight language="config"> |
| UndefMacro LocalAccessPolicy |
| UndefMacro RestrictedAccessPolicy |
| </highlight> |
| </usage> |
| </directivesynopsis> |
| |
| <!-- MacroIgnoreEmptyArg --> |
| <directivesynopsis> |
| <name>MacroIgnoreEmptyArgs</name> |
| <description>Ignore warnings, and does not log, about empty Macro argument(s)</description> |
| |
| <syntax>MacroIgnoreEmptyArgs</syntax> |
| <contextlist> |
| <context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <override>All</override> |
| |
| </directivesynopsis> |
| |
| <!-- MacroIgnoreBadNesting --> |
| <directivesynopsis> |
| <name>MacroIgnoreBadNesting</name> |
| <description>Ignore warnings, and does not log, about bad nesting of Macros</description> |
| |
| <syntax>MacroIgnoreBadNesting</syntax> |
| <contextlist> |
| <context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <override>All</override> |
| |
| </directivesynopsis> |
| |
| </modulesynopsis> |