f545d156561c08020a67f9640c51454c2df4fb57fabien<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f545d156561c08020a67f9640c51454c2df4fb57fabien<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
b4ddd0004bc04c857001f9f5e4600f3957054a32nd<!-- $LastChangedRevision$ -->
f545d156561c08020a67f9640c51454c2df4fb57fabien Licensed to the Apache Software Foundation (ASF) under one or more
f545d156561c08020a67f9640c51454c2df4fb57fabien contributor license agreements. See the NOTICE file distributed with
f545d156561c08020a67f9640c51454c2df4fb57fabien this work for additional information regarding copyright ownership.
f545d156561c08020a67f9640c51454c2df4fb57fabien The ASF licenses this file to You under the Apache License, Version 2.0
f545d156561c08020a67f9640c51454c2df4fb57fabien (the "License"); you may not use this file except in compliance with
f545d156561c08020a67f9640c51454c2df4fb57fabien the License. You may obtain a copy of the License at
f545d156561c08020a67f9640c51454c2df4fb57fabien Unless required by applicable law or agreed to in writing, software
f545d156561c08020a67f9640c51454c2df4fb57fabien distributed under the License is distributed on an "AS IS" BASIS,
f545d156561c08020a67f9640c51454c2df4fb57fabien WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
f545d156561c08020a67f9640c51454c2df4fb57fabien See the License for the specific language governing permissions and
f545d156561c08020a67f9640c51454c2df4fb57fabien limitations under the License.
f3d0c7823381704cd2977a45cdc490515bda49b6rbowen<description>Provides macros within apache httpd runtime configuration files</description>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen <p>Provides macros within Apache httpd runtime configuration files,
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen to ease the process of creating numerous similar configuration
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen blocks. When the server starts up, the macros are expanded using the
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen provided parameters, and the result is processed as along with the
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen rest of the configuration file.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowentype="section">Macro</directive> blocks, which contain the portion of
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenyour configuration that needs to be repeated, complete with variables
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenfor those parts that will need to be substituted.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>For example, you might use a macro to define a <directive
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowentype="section">VirtualHost</directive> block, in order to define
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenmultiple similar virtual hosts:</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<Macro VHost $name $domain>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<VirtualHost *:80>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen ServerName $domain
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen ServerAlias www.$domain
430b9854ae290aa3f76164c93193c6c11ace5c0crbowen</VirtualHost>
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen</highlight>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>Macro names are case-insensitive, like httpd configuration
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowendirectives. However, variable names are case sensitive.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>You would then invoke this macro several times to create virtual
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenUse VHost example example.com
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenUse VHost myhost hostname.org
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenUse VHost apache apache.org
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenUndefMacro VHost
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen</highlight>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>At server startup time, each of these <directive>Use</directive>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rboweninvocations would be expanded into a full virtualhost, as
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowendescribed by the <directive>Macro</directive> definition.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>The <directive>UndefMacro</directive> directive is used so that later
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenmacros using the same variable names don't result in conflicting
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowendefinitions.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>A more elaborate version of this example may be seen below in the
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenExamples section.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>Parameter names should begin with a sigil such as <code>$</code>,
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<code>%</code>, or <code>@</code>, so that they are clearly
ddec0304f69a508de2b1b9c018e308218c766a56igalicidentifiable, and also in order to help deal with interactions with
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenother directives, such as the core <directive
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarmodule="core">Define</directive> directive. Failure to do so will
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenresult in a warning. Nevertheless, you are encouraged to have a good
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenknowledge of your entire server configuration in order to avoid reusing
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenthe same variables in different scopes, which can cause confusion.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>Parameters prefixed with either <code>$</code> or <code>%</code> are
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowennot escaped. Parameters prefixes with <code>@</code> are escaped in
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>Avoid using a parameter which contains another parameter as a prefix,
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen(For example, <code>$win</code> and <code>$winter</code>) as this may
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowencause confusion at expression evaluation time. In the event of such
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenconfusion, the longest possible parameter name is used.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>If you want to use a value within another string, it is useful to
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowensurround the parameter in braces, to avoid confusion:</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<Macro DocRoot ${docroot}>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen</Macro>
9546947d8f7082fb4b70e1659feb5460502b73e4rbowen</highlight>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen<p>A common usage of <module>mod_macro</module> 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
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coar DocumentRoot "$dir"
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen # Public document root
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <Directory "$dir">
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen Require all granted
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen </Directory>
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen # limit access to intranet subdir.
a399e0d46b76c0bd93d7a9cb1c14c8ce5de5af62rbowen 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
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen</highlight>
dbcc3b8b7010c645cf63f2135193bc148ee3db4drbowen<p>It's recommended that you undefine a macro once you've used it. This
dbcc3b8b7010c645cf63f2135193bc148ee3db4drbowenavoids confusion in a complex configuration file where there may be
6d92f6ca27b32822e9a78596f4ab561cd65b7016rbowenconflicts in variable names.</p>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<Macro DirGroup $dir $group>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <Directory "$dir">
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen Require group $group
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen </Directory>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen</Macro>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenUndefMacro DirGroup
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen</highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien<!-- Macro -->
f545d156561c08020a67f9640c51454c2df4fb57fabien<description>Define a configuration file macro</description>
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]>
f545d156561c08020a67f9640c51454c2df4fb57fabien... </Macro></syntax>
f545d156561c08020a67f9640c51454c2df4fb57fabien<contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien</contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien <p>The <directive>Macro</directive> directive controls the definition of
f545d156561c08020a67f9640c51454c2df4fb57fabien a macro within the server runtime configuration files.
f545d156561c08020a67f9640c51454c2df4fb57fabien The first argument is the name of the macro.
f545d156561c08020a67f9640c51454c2df4fb57fabien Other arguments are parameters to the macro. It is good practice to prefix
f545d156561c08020a67f9640c51454c2df4fb57fabien parameter names with any of '<code>$%@</code>', and not macro names
f545d156561c08020a67f9640c51454c2df4fb57fabien with such characters.
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro LocalAccessPolicy>
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
f545d156561c08020a67f9640c51454c2df4fb57fabien<Macro RestrictedAccessPolicy $ipnumbers>
fe89484abca7439b98b250ee9091da29089c2bdarbowen Require ip $ipnumbers
f545d156561c08020a67f9640c51454c2df4fb57fabien</Macro>
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien</directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<!-- Use -->
f545d156561c08020a67f9640c51454c2df4fb57fabien<directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<syntax>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
f545d156561c08020a67f9640c51454c2df4fb57fabien<contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien</contextlist>
9546947d8f7082fb4b70e1659feb5460502b73e4rbowen <p>The <directive>Use</directive> directive controls the use of a macro.
f545d156561c08020a67f9640c51454c2df4fb57fabien The specified macro is expanded. It must be given the same number of
ddec0304f69a508de2b1b9c018e308218c766a56igalic arguments as in the macro definition. The provided values are
f545d156561c08020a67f9640c51454c2df4fb57fabien associated to their corresponding initial parameters and are substituted
f545d156561c08020a67f9640c51454c2df4fb57fabien before processing.</p>
f3d0c7823381704cd2977a45cdc490515bda49b6rbowenUse LocalAccessPolicy
f3d0c7823381704cd2977a45cdc490515bda49b6rbowenUse RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien</directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<!-- UndefMacro -->
f545d156561c08020a67f9640c51454c2df4fb57fabien<directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien<contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien</contextlist>
f545d156561c08020a67f9640c51454c2df4fb57fabien <p>The <directive>UndefMacro</directive> directive undefines a macro
f545d156561c08020a67f9640c51454c2df4fb57fabien which has been defined before hand.</p>
f545d156561c08020a67f9640c51454c2df4fb57fabienUndefMacro LocalAccessPolicy
f545d156561c08020a67f9640c51454c2df4fb57fabienUndefMacro RestrictedAccessPolicy
f545d156561c08020a67f9640c51454c2df4fb57fabien </highlight>
f545d156561c08020a67f9640c51454c2df4fb57fabien</directivesynopsis>
f545d156561c08020a67f9640c51454c2df4fb57fabien</modulesynopsis>