2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1533274 -->
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>
36 <p>Ce module permet d'utiliser des macros dans les fichiers de
37 configuration à l'exécution du serveur HTTP Apache afin de faciliter
38 la création de nombreux blocs de configuration similaires. Quand le
39 serveur démarre, les macros sont exécutées avec les paramètres
40 fournis, et le résultat obtenu est traité au même titre que le reste
41 du fichier de configuration.</p>
45 <section id="usage"><title>Utilisation</title>
46 <p>On définit une macro à l'aide des blocs <directive
47 type="section">Macro</directive> qui contiennent la portion de votre
48 configuration qui intervient de manière répétitive, y compris les
49 variables pour les parties qui devront être substituées.</p>
51 <p>Par exemple, vous pouvez utiliser une macro pour définir un bloc
52 <directive type="section">VirtualHost</directive>, afin de pouvoir
53 définir de nombreux serveurs virtuels similaires :</p>
55 <highlight language="config">
56 <Macro VHost $name $domain>
57 <VirtualHost *:80>
59 ServerAlias www.$domain
61 DocumentRoot /var/www/vhosts/$name
62 ErrorLog /var/log/httpd/$name.error_log
63 CustomLog /var/log/httpd/$name.access_log combined
68 <p>Comme les directives de configuration httpd, les noms des macros sont
69 insensibles à la casse, à la différence des variables qui y sont, elles,
72 <p>Vous pouvez alors invoquer cette macro autant de fois que vous le
73 voulez pour créer des serveurs virtuels </p>
75 <highlight language="config">
76 Use VHost example example.com
77 Use VHost myhost hostname.org
78 Use VHost apache apache.org
83 <p>Au démarrage du serveur, chacune de ces invocations
84 <directive>Use</directive> sera remplacée par une définition de serveur
85 virtuel complète, comme décrit dans la définition de la
86 <directive>Macro</directive>.</p>
88 <p>La directive <directive>UndefMacro</directive> permet d'éviter les
89 conflits de définitions qui pourraient provenir de l'utilisation
90 ultérieure de macros contenant les mêmes noms de variables.</p>
92 <p>Vous trouverez une version plus élaborée de cet exemple plus loin
93 dans la section Exemples.</p>
97 <section id="tips"><title>Conseils</title>
99 <p>Les noms de paramètres doivent commencer par un sigil tel que
100 <code>$</code>, <code>%</code>, ou <code>@</code>, de façon à ce qu'ils
101 soient clairement identifiables, mais aussi afin de faciliter les
102 interactions avec les autres directives, comme la directive de base
103 <directive module="core">Define</directive>. Dans le cas contraire, vous
104 recevrez un avertissement. En tout état de cause, il est conseillé
105 d'avoir une bonne connaissance globale de la configuration du serveur,
106 afin d'éviter la réutilisation des mêmes variables à différents niveaux,
107 ce qui peut être à l'origine de confusions.</p>
109 <p>Les paramètres préfixés par <code>$</code> ou <code>%</code> ne sont
110 pas échappés. Les paramètres préfixés par <code>@</code> sont échappés
111 entre guillemets.</p>
113 <p>Evitez de préfixer un paramètre par le nom d'un autre paramètre (par
114 exemple, présence simultanée des paramètres <code>$win</code> et
115 <code>$winter</code>), car ceci peut introduire de la confusion lors de
116 l'évaluation des expressions. Si cela se produit, c'est le nom de
117 paramètre le plus long possible qui sera utilisé.</p>
119 <p>Si vous désirez insérer une valeur dans une chaîne, il est conseillé
120 de l'entourer d'accolades afin d'éviter toute confusion :</p>
122 <highlight language="config">
123 <Macro DocRoot ${docroot}>
124 DocumentRoot /var/www/${docroot}/htdocs
130 <section id="examples">
131 <title>Exemples</title>
134 <title>Définition de serveurs virtuels</title>
136 <p>Un exemple typique d'utilisation de <module>mod_macro</module> est la
137 création dynamique de serveurs virtuels.</p>
139 <highlight language="config">
140 ## Définition d'une macro VHost pour les configurations répétitives
142 <Macro VHost $host $port $dir>
144 <VirtualHost *:$port>
149 # Racine des documents publique
150 <Directory $dir>
154 # restriction d'accès au sous-répertoire intranet.
155 <Directory $dir/intranet>
156 Require ip 10.0.0.0/8
161 ## Utilisation de la macro VHost avec différents arguments.
163 Use VHost www.apache.org 80 /vhosts/apache/htdocs
164 Use VHost example.org 8080 /vhosts/example/htdocs
165 Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs
167 </section> <!-- Vhosts -->
170 <title>Suppression d'une définition de macro</title>
172 <p>Il est recommandé de supprimer la définition d'une macro après
173 l'avoir utilisée. Ceci permet d'éviter les confusions au sein d'un
174 fichier de configuration complexe où des conflits entre noms de
175 variables peuvent survenir.</p>
177 <highlight language="config">
178 <Macro DirGroup $dir $group>
179 <Directory $dir>
184 Use DirGroup /www/apache/private private
185 Use DirGroup /www/apache/server admin
190 </section> <!-- UndefMacro -->
192 </section> <!-- Example -->
195 <directivesynopsis type="section">
197 <description>Définition d'une macro dans un fichier de configuration</description>
199 <Macro <var>nom</var> [<var>par1</var> .. <var>parN</var>]>
200 ... </Macro></syntax>
202 <context>server config</context>
203 <context>virtual host</context>
204 <context>directory</context>
208 <p>La directive <directive>Macro</directive> permet de définir une macro
209 dans un fichier de configuration Apache. Le premier argument est le nom
210 de la macro, et les arguments suivants sont les paramètres. Il
211 est de bon aloi de préfixer les noms des paramètres d'une macro
212 avec un caractère parmi '<code>$%@</code>', et d'éviter d'en faire
213 de même avec les noms de macros.
216 <highlight language="config">
217 <Macro LocalAccessPolicy>
218 Require ip 10.2.16.0/24
221 <Macro RestrictedAccessPolicy $ipnumbers>
222 Require ip $ipnumbers
231 <description>Utilisation d'une macro</description>
232 <syntax>Use <var>nom</var> [<var>valeur1</var> ... <var>valeurN</var>]
235 <context>server config</context>
236 <context>virtual host</context>
237 <context>directory</context>
241 <p> La directive <directive>Use</directive> permet d'utiliser une macro.
242 La macro considérée est expansée. Son nombre d'arguments doit être égal au
243 nombre de paramètres précisés dans sa définition. Les valeurs passées en
244 argument sont attribuées aux paramètres correspondants et
245 substituées avant l'interprétation du texte de la macro.</p>
247 <highlight language="config">
248 Use LocalAccessPolicy
250 Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
253 <p>est équivalent, avec les macros définies ci-dessus à :</p>
255 <highlight language="config">
256 Require ip 10.2.16.0/24
258 Require ip 192.54.172.0/24 192.54.148.0/24
265 <name>undefMacro</name>
266 <description>Supprime une macro</description>
268 <syntax>UndefMacro <var>nom</var></syntax>
270 <context>server config</context>
271 <context>virtual host</context>
272 <context>directory</context>
276 <p>La directive <directive>UndefMacro</directive> annule la définition
277 d'une macro qui doit avoir été définie auparavant.</p>
279 <highlight language="config">
280 UndefMacro LocalAccessPolicy
281 UndefMacro RestrictedAccessPolicy