1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1850539 -->
5 <!-- French translation: Fabien Coelho -->
6 <!-- Updated by Lucien Gentis -->
9 Licensed to the Apache Software Foundation (ASF) under one or more
10 contributor license agreements. See the NOTICE file distributed with
11 this work for additional information regarding copyright ownership.
12 The ASF licenses this file to You under the Apache License, Version 2.0
13 (the "License"); you may not use this file except in compliance with
14 the License. You may obtain a copy of the License at
16 http://www.apache.org/licenses/LICENSE-2.0
18 Unless required by applicable law or agreed to in writing, software
19 distributed under the License is distributed on an "AS IS" BASIS,
20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 See the License for the specific language governing permissions and
22 limitations under the License.
25 <modulesynopsis metafile="mod_macro.xml.meta">
27 <name>mod_macro</name>
28 <description>Ce module permet d'utiliser des macros dans les fichiers
29 de configuration Apache.</description>
31 <sourcefile>mod_macro.c</sourcefile>
32 <identifier>macro_module</identifier>
33 <compatibility>Disponible à partir de la version 2.4.5 du serveur HTTP Apache</compatibility>
37 <p>Ce module permet d'utiliser des macros dans les fichiers de
38 configuration à l'exécution du serveur HTTP Apache afin de faciliter
39 la création de nombreux blocs de configuration similaires. Quand le
40 serveur démarre, les macros sont exécutées avec les paramètres
41 fournis, et le résultat obtenu est traité au même titre que le reste
42 du fichier de configuration.</p>
46 <section id="usage"><title>Utilisation</title>
47 <p>On définit une macro à l'aide des blocs <directive module="mod_macro"
48 type="section">Macro</directive> qui contiennent la portion de votre
49 configuration qui intervient de manière répétitive, y compris les
50 variables pour les parties qui devront être substituées.</p>
52 <p>Par exemple, vous pouvez utiliser une macro pour définir un bloc
53 <directive module="core" type="section">VirtualHost</directive>, afin de pouvoir
54 définir de nombreux serveurs virtuels similaires :</p>
56 <highlight language="config">
57 <Macro VHost $name $domain>
58 <VirtualHost *:80>
60 ServerAlias www.$domain
62 DocumentRoot "/var/www/vhosts/$name"
63 ErrorLog "/var/log/httpd/$name.error_log"
64 CustomLog "/var/log/httpd/$name.access_log" combined
69 <p>Comme les directives de configuration httpd, les noms des macros sont
70 insensibles à la casse, à la différence des variables qui y sont, elles,
73 <p>Vous pouvez alors invoquer cette macro autant de fois que vous le
74 voulez pour créer des serveurs virtuels </p>
76 <highlight language="config">
77 Use VHost example example.com
78 Use VHost myhost hostname.org
79 Use VHost apache apache.org
84 <p>Au démarrage du serveur, chacune de ces invocations
85 <directive module="mod_macro">Use</directive> sera remplacée par une définition de serveur
86 virtuel complète, comme décrit dans la définition de la
87 <directive module="mod_macro" type="section">Macro</directive>.</p>
89 <p>La directive <directive module="mod_macro">UndefMacro</directive> permet d'éviter les
90 conflits de définitions qui pourraient provenir de l'utilisation
91 ultérieure de macros contenant les mêmes noms de variables.</p>
93 <p>Vous trouverez une version plus élaborée de cet exemple plus loin
94 dans la section Exemples.</p>
98 <section id="tips"><title>Conseils</title>
100 <p>Les noms de paramètres doivent commencer par un sigil tel que
101 <code>$</code>, <code>%</code>, ou <code>@</code>, de façon à ce qu'ils
102 soient clairement identifiables, mais aussi afin de faciliter les
103 interactions avec les autres directives, comme la directive de base
104 <directive module="core">Define</directive>. Dans le cas contraire, vous
105 recevrez un avertissement. En tout état de cause, il est conseillé
106 d'avoir une bonne connaissance globale de la configuration du serveur,
107 afin d'éviter la réutilisation des mêmes variables à différents niveaux,
108 ce qui peut être à l'origine de confusions.</p>
110 <p>Les paramètres préfixés par <code>$</code> ou <code>%</code> ne sont
111 pas échappés. Les paramètres préfixés par <code>@</code> sont échappés
112 entre guillemets.</p>
114 <p>Evitez de préfixer un paramètre par le nom d'un autre paramètre (par
115 exemple, présence simultanée des paramètres <code>$win</code> et
116 <code>$winter</code>), car ceci peut introduire de la confusion lors de
117 l'évaluation des expressions. Si cela se produit, c'est le nom de
118 paramètre le plus long possible qui sera utilisé.</p>
120 <p>Si vous désirez insérer une valeur dans une chaîne, il est conseillé
121 de l'entourer d'accolades afin d'éviter toute confusion :</p>
123 <highlight language="config">
124 <Macro DocRoot ${docroot}>
125 DocumentRoot "/var/www/${docroot}/htdocs"
131 <section id="examples">
132 <title>Exemples</title>
135 <title>Définition de serveurs virtuels</title>
137 <p>Un exemple typique d'utilisation de <module>mod_macro</module> est la
138 création dynamique de serveurs virtuels.</p>
140 <highlight language="config">
141 ## Définition d'une macro VHost pour les configurations répétitives
143 <Macro VHost $host $port $dir>
145 <VirtualHost *:$port>
150 # Racine des documents publique
151 <Directory "$dir">
155 # restriction d'accès au sous-répertoire intranet.
156 <Directory "$dir/intranet">
157 Require ip 10.0.0.0/8
162 ## Utilisation de la macro VHost avec différents arguments.
164 Use VHost www.apache.org 80 /vhosts/apache/htdocs
165 Use VHost example.org 8080 /vhosts/example/htdocs
166 Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs
168 </section> <!-- Vhosts -->
171 <title>Suppression d'une définition de macro</title>
173 <p>Il est recommandé de supprimer la définition d'une macro après
174 l'avoir utilisée. Ceci permet d'éviter les confusions au sein d'un
175 fichier de configuration complexe où des conflits entre noms de
176 variables peuvent survenir.</p>
178 <highlight language="config">
179 <Macro DirGroup $dir $group>
180 <Directory "$dir">
185 Use DirGroup /www/apache/private private
186 Use DirGroup /www/apache/server admin
191 </section> <!-- UndefMacro -->
193 </section> <!-- Example -->
196 <directivesynopsis type="section">
198 <description>Définition d'une macro dans un fichier de configuration</description>
200 <Macro <var>nom</var> [<var>par1</var> .. <var>parN</var>]>
201 ... </Macro></syntax>
203 <context>server config</context>
204 <context>virtual host</context>
205 <context>directory</context>
207 <override>All</override>
210 <p>La directive <directive type="section">Macro</directive> permet de définir une macro
211 dans un fichier de configuration Apache. Le premier argument est le nom
212 de la macro, et les arguments suivants sont les paramètres. Il
213 est de bon aloi de préfixer les noms des paramètres d'une macro
214 avec un caractère parmi '<code>$%@</code>', et d'éviter d'en faire
215 de même avec les noms de macros.
218 <highlight language="config">
219 <Macro LocalAccessPolicy>
220 Require ip 10.2.16.0/24
223 <Macro RestrictedAccessPolicy $ipnumbers>
224 Require ip $ipnumbers
233 <description>Utilisation d'une macro</description>
234 <syntax>Use <var>nom</var> [<var>valeur1</var> ... <var>valeurN</var>]
237 <context>server config</context>
238 <context>virtual host</context>
239 <context>directory</context>
241 <override>All</override>
244 <p> La directive <directive>Use</directive> permet d'utiliser une macro.
245 La macro considérée est expansée. Son nombre d'arguments doit être égal au
246 nombre de paramètres précisés dans sa définition. Les valeurs passées en
247 argument sont attribuées aux paramètres correspondants et
248 substituées avant l'interprétation du texte de la macro.</p>
250 <highlight language="config">
251 Use LocalAccessPolicy
253 Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
256 <p>est équivalent, avec les macros définies ci-dessus à :</p>
258 <highlight language="config">
259 Require ip 10.2.16.0/24
261 Require ip 192.54.172.0/24 192.54.148.0/24
268 <name>UndefMacro</name>
269 <description>Supprime une macro</description>
271 <syntax>UndefMacro <var>nom</var></syntax>
273 <context>server config</context>
274 <context>virtual host</context>
275 <context>directory</context>
277 <override>All</override>
280 <p>La directive <directive>UndefMacro</directive> annule la définition
281 d'une macro qui doit avoir été définie auparavant.</p>
283 <highlight language="config">
284 UndefMacro LocalAccessPolicy
285 UndefMacro RestrictedAccessPolicy
290 <!-- MacroIgnoreEmptyArg -->
292 <name>MacroIgnoreEmptyArgs</name>
293 <description>Ignore les avertissements et n'inscrit rien dans le journal à
294 propos des arguments de Macro vides</description>
296 <syntax>MacroIgnoreEmptyArgs</syntax>
298 <context>server config</context>
299 <context>virtual host</context>
300 <context>directory</context>
302 <override>All</override>
306 <!-- MacroIgnoreBadNesting -->
308 <name>MacroIgnoreBadNesting</name>
309 <description>Ignore les avertissements et n'inscrit rien dans le journal à
310 propos d'une imbrication de Macros non conforme</description>
312 <syntax>MacroIgnoreBadNesting</syntax>
314 <context>server config</context>
315 <context>virtual host</context>
316 <context>directory</context>
318 <override>All</override>