0N/A<?xml version="1.0"?>

1472N/A<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

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

0N/A

0N/A

0N/A<modulesynopsis metafile="mod_macro.xml.meta">

0N/A

0N/A<name>mod_macro</name>

0N/A<description>Provides macros within apache httpd runtime configuration files</description>

0N/A<status>Base</status>

0N/A<sourcefile>mod_macro.c</sourcefile>

0N/A<identifier>macro_module</identifier>

0N/A

0N/A<summary>

0N/A

0N/A <p>Provides macros within Apache httpd runtime configuration files,

0N/A to ease the process of creating numerous similar configuration

0N/A blocks. When the server starts up, the macros are expanded using the

0N/A provided parameters, and the result is processed as along with the

0N/A rest of the configuration file.</p>

0N/A

0N/A</summary>

0N/A

0N/A<section id="usage"><title>Usage</title>

0N/A

0N/A<p>Macros are defined using <directive

0N/Atype="section">Macro</directive> blocks, which contain the portion of

0N/Ayour configuration that needs to be repeated, complete with variables

0N/Afor those parts that will need to be substituted.</p>

0N/A

0N/A<p>For example, you might use a macro to define a <directive

0N/Atype="section">VirtualHost</directive> block, in order to define

0N/Amultiple similar virtual hosts:</p>

0N/A

0N/A<highlight language="config">

0N/A&lt;Macro VHost $name $domain&gt;

0N/A&lt;VirtualHost *:80&gt;

0N/A ServerName $domain

0N/A ServerAlias www.$domain

0N/A

0N/A DocumentRoot /var/www/vhosts/$name

0N/A ErrorLog /var/log/httpd/$name.error_log

0N/A CustomLog /var/log/httpd/name.access_log combined

0N/A&gt;/VirtualHost&gt;

0N/A&lt;/Macro&gt;

0N/A</highlight>

0N/A

0N/A<p>Macro names are case-insensitive, like httpd configuration

0N/Adirectives. However, variable names are case sensitive.</p>

0N/A

0N/A<p>You would then invoke this macro several times to create virtual

0N/Ahosts:</p>

0N/A

0N/A<highlight language="config">

0N/AUse VHost example example.com

0N/AUse VHost myhost hostname.org

0N/AUse VHost apache apache.org

0N/A

0N/AUndefMacro VHost

0N/A</highlight>

0N/A

0N/A<p>At server startup time, each of these <directive>Use</directive>

0N/Ainvocations would be expanded into a full virtualhost, as

0N/Adescribed by the <directive>Macro</directive> definition.</p>

0N/A

0N/A<p>The <directive>UndefMacro</directive> directive is used so that later

0N/Amacros using the same variable names don't result in conflicting

0N/Adefinitions.</p>

0N/A

0N/A<p>A more elaborate version of this example may be seen below in the

0N/AExamples section.</p>

0N/A

0N/A</section>

0N/A

0N/A<section id="tips"><title>Tips</title>

0N/A

0N/A<p>Parameter names should begin with a sigil such as <code>$</code>,

0N/A<code>%</code>, or <code>@</code>, so that they are clearly

0N/Aidentifiable, and also in order to help deail with interactions with

0N/Aother directives, such as the core <directive

0N/Amodule="core">Define</directive> directive. Failure to do so will

0N/Aresult in a warning. Nevertheless, you are encouraged to have a good

0N/Aknowledge of your entire server configuration in order to avoid reusing

0N/Athe same variables in different scopes, which can cause confusion.</p>

0N/A

0N/A<p>Parameters prefixed with either <code>$</code> or <code>%</code> are

0N/Anot escaped. Parameters prefixes with <code>@</code> are escaped in

0N/Aquotes.</p>

0N/A

0N/A<p>Avoid using a parameter which contains another parameter as a prefix,

0N/A(For example, <code>$win</code> and <code>$winter</code>) as this may

0N/Acause confusion at expression evaluation time. In the event of such

0N/Aconfusion, the longest possible parameter name is used.</p>

0N/A

0N/A<p>If you want to use a value within another string, it is useful to

0N/Asurround the parameter in braces, to avoid confusion:</p>

0N/A

0N/A<highlight language="config">

0N/A&lt;Macro DocRoot ${docroot}&gt;

0N/A DocumentRoot /var/www/${docroot}/htdocs

0N/A&lt;/Macro&gt;

0N/A</highlight>

0N/A

0N/A</section>

0N/A

0N/A<section id="examples">

0N/A<title>Examples</title>

0N/A

0N/A<section>

0N/A<title>Virtual Host Definition</title>

0N/A

0N/A<p>A common usage of <module>mod_macro</module> is for the creation of

0N/Adynamically-generated virtual hosts.</p>

0N/A

0N/A<highlight language="config">

0N/A## Define a VHost Macro for repetitive configurations

0N/A

0N/A&lt;Macro VHost $host $port $dir&gt;

0N/A Listen $port

0N/A &lt;VirtualHost *:$port&gt;

0N/A

0N/A ServerName $host

0N/A DocumentRoot $dir

0N/A

0N/A # Public document root

0N/A &lt;Directory $dir&gt;

0N/A Require all granted

0N/A &lt;/Directory&gt;

0N/A

0N/A # limit access to intranet subdir.

0N/A &lt;Directory $dir/intranet&gt;

0N/A Require ip 10.0.0.0/8

0N/A &lt;/Directory&gt;

0N/A &lt;/VirtualHost&gt;

0N/A&lt;/Macro&gt;

0N/A

0N/A## Use of VHost with different arguments.

0N/A

0N/AUse VHost www.apache.org 80 /vhosts/apache/htdocs

0N/AUse VHost example.org 8080 /vhosts/example/htdocs

0N/AUse VHost www.example.fr 1234 /vhosts/example.fr/htdocs

0N/A</highlight>

0N/A</section> <!-- Vhosts -->

0N/A

0N/A<section>

0N/A<title>Removal of a macro definition</title>

0N/A

0N/A<p>It's recommended that you undefine a macro once you've used it. This

0N/Aavoids confusion in a complex configuration file where there may be

0N/Aconflicts in variable names.</p>

0N/A

0N/A<highlight language="config">

0N/A&lt;Macro DirGroup $dir $group&gt;

0N/A &lt;Directory $dir&gt;

0N/A Require group $group

0N/A &lt;/Directory&gt;

0N/A&lt;/Macro&gt;

0N/A

0N/AUse DirGroup /www/apache/private private

0N/AUse DirGroup /www/apache/server admin

0N/A

0N/AUndefMacro DirGroup

0N/A</highlight>

0N/A

0N/A</section> <!-- UndefMacro -->

0N/A

0N/A</section> <!-- Example -->

0N/A

0N/A<directivesynopsis type="section">

0N/A<name>Macro</name>

0N/A<description>Define a configuration file macro</description>

0N/A<syntax>

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

0N/A... &lt;/Macro&gt;</syntax>

0N/A<contextlist>

0N/A<context>server config</context>

0N/A<context>virtual host</context>

0N/A<context>directory</context>

0N/A</contextlist>

0N/A

0N/A<usage>

0N/A <p>The <directive>Macro</directive> directive controls the definition of

0N/A a macro within the server runtime configuration files.

0N/A The first argument is the name of the macro.

0N/A Other arguments are parameters to the macro. It is good practice to prefix

0N/A parameter names with any of '<code>$%@</code>', and not macro names

0N/A with such characters.

0N/A </p>

0N/A

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