mod_macro.xml revision cc6e9d4eadba6737e59af04f794d4a9ffb1750c7
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
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen>/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<section id="details"><title>Technical details</title>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<p>Parameter names should begin with a sigil such as <code>$</code>,
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<code>%</code>, or <code>@</code>, so that they are clearly
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenidentifiable, and also in order to help deail with interactions with
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenother directives, such as the core <directive
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowenmodule="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
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen DocumentRoot $dir
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen # Public document root
3b35091b9c1ae36ee3d0e64ebbfdba58062290ffrbowen <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>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen<Macro DirGroup $dir $group>
cc6e9d4eadba6737e59af04f794d4a9ffb1750c7rbowen <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
f545d156561c08020a67f9640c51454c2df4fb57fabien arguments than 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>