<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<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>

<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

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

type="section">VirtualHost</directive> block, in order to define

multiple similar virtual hosts:</p>

<highlight language="config">

&lt;Macro VHost $name $domain&gt;

&lt;VirtualHost *:80&gt;

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

&lt;/VirtualHost&gt;

&lt;/Macro&gt;

</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>Use</directive>

invocations would be expanded into a full virtualhost, as

described by the <directive>Macro</directive> definition.</p>

<p>The <directive>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">

&lt;Macro DocRoot ${docroot}&gt;

DocumentRoot "/var/www/${docroot}/htdocs"

&lt;/Macro&gt;

</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

&lt;Macro VHost $host $port $dir&gt;

Listen $port

&lt;VirtualHost *:$port&gt;

ServerName $host

DocumentRoot "$dir"

# Public document root

&lt;Directory "$dir"&gt;

Require all granted

&lt;/Directory&gt;

# limit access to intranet subdir.

&lt;Directory "$dir/intranet"&gt;

Require ip 10.0.0.0/8

&lt;/Directory&gt;

&lt;/VirtualHost&gt;

&lt;/Macro&gt;

## 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">

&lt;Macro DirGroup $dir $group&gt;

&lt;Directory "$dir"&gt;

Require group $group

&lt;/Directory&gt;

&lt;/Macro&gt;

Use DirGroup /www/apache/private private

Use DirGroup /www/apache/server admin

UndefMacro DirGroup

</highlight>

</section> <!-- UndefMacro -->

</section> <!-- Example -->

<directivesynopsis type="section">

<name>Macro</name>

<description>Define a configuration file macro</description>

<syntax>

&lt;Macro <var>name</var> [<var>par1</var> .. <var>parN</var>]&gt;

... &lt;/Macro&gt;</syntax>

<contextlist>

<context>server config</context>

<context>virtual host</context>

<context>directory</context>

</contextlist>

<usage>

<p>The <directive>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">

&lt;Macro LocalAccessPolicy&gt;

Require ip 10.2.16.0/24

&lt;/Macro&gt;

&lt;Macro RestrictedAccessPolicy $ipnumbers&gt;

Require ip $ipnumbers

&lt;/Macro&gt;

</highlight>

</usage>

</directivesynopsis>

<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>

<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>

<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>

<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>

</modulesynopsis>