[apache] / docs / manual / mod / mod_macro.xml.fr

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
<!-- English Revision: 1560082 -->
<!-- French translation: Fabien Coelho -->
<!-- Updated by Lucien Gentis -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_macro.xml.meta">

<name>mod_macro</name>
<description>Ce module permet d'utiliser des macros dans les fichiers
de configuration Apache.</description>
<status>Base</status>
<sourcefile>mod_macro.c</sourcefile>
<identifier>macro_module</identifier>

<summary>

    <p>Ce module permet d'utiliser des macros dans les fichiers de
    configuration &agrave; l'ex&eacute;cution du serveur HTTP Apache afin de faciliter
    la cr&eacute;ation de nombreux blocs de configuration similaires. Quand le
    serveur d&eacute;marre, les macros sont ex&eacute;cut&eacute;es avec les param&egrave;tres
    fournis, et le r&eacute;sultat obtenu est trait&eacute; au m&ecirc;me titre que le reste
    du fichier de configuration.</p>

</summary>

<section id="usage"><title>Utilisation</title>    
<p>On d&eacute;finit une macro &agrave; l'aide des blocs <directive
type="section">Macro</directive> qui contiennent la portion de votre
configuration qui intervient de mani&egrave;re r&eacute;p&eacute;titive, y compris les
variables pour les parties qui devront &ecirc;tre substitu&eacute;es.</p>

<p>Par exemple, vous pouvez utiliser une macro pour d&eacute;finir un bloc
<directive type="section">VirtualHost</directive>, afin de pouvoir
d&eacute;finir de nombreux serveurs virtuels similaires :</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>Comme les directives de configuration httpd, les noms des macros sont
insensibles &agrave; la casse, &agrave; la diff&eacute;rence des variables qui y sont, elles,
sensibles.</p>

<p>Vous pouvez alors invoquer cette macro autant de fois que vous le
voulez pour cr&eacute;er des serveurs virtuels </p>

<highlight language="config">
Use VHost example example.com
Use VHost myhost hostname.org
Use VHost apache apache.org

UndefMacro VHost
    </highlight>

<p>Au d&eacute;marrage du serveur, chacune de ces invocations
<directive>Use</directive> sera remplac&eacute;e par une d&eacute;finition de serveur
virtuel compl&egrave;te, comme d&eacute;crit dans la d&eacute;finition de la
<directive>Macro</directive>.</p>

<p>La directive <directive>UndefMacro</directive> permet d'&eacute;viter les
conflits de d&eacute;finitions qui pourraient provenir de l'utilisation
ult&eacute;rieure de macros contenant les m&ecirc;mes noms de variables.</p>

<p>Vous trouverez une version plus &eacute;labor&eacute;e de cet exemple plus loin
dans la section Exemples.</p>

</section>

<section id="tips"><title>Conseils</title>

<p>Les noms de param&egrave;tres doivent commencer par un sigil tel que
<code>$</code>, <code>%</code>, ou <code>@</code>, de fa&ccedil;on &agrave; ce qu'ils
soient clairement identifiables, mais aussi afin de faciliter les
interactions avec les autres directives, comme la directive de base
<directive module="core">Define</directive>. Dans le cas contraire, vous
recevrez un avertissement. En tout &eacute;tat de cause, il est conseill&eacute;
d'avoir une bonne connaissance globale de la configuration du serveur,
afin d'&eacute;viter la r&eacute;utilisation des m&ecirc;mes variables &agrave; diff&eacute;rents niveaux,
ce qui peut &ecirc;tre &agrave; l'origine de confusions.</p>

<p>Les param&egrave;tres pr&eacute;fix&eacute;s par <code>$</code> ou <code>%</code> ne sont
pas &eacute;chapp&eacute;s. Les param&egrave;tres pr&eacute;fix&eacute;s par <code>@</code> sont &eacute;chapp&eacute;s
entre guillemets.</p>

<p>Evitez de pr&eacute;fixer un param&egrave;tre par le nom d'un autre param&egrave;tre (par
exemple, pr&eacute;sence simultan&eacute;e des param&egrave;tres <code>$win</code> et
<code>$winter</code>), car ceci peut introduire de la confusion lors de
l'&eacute;valuation des expressions. Si cela se produit, c'est le nom de
param&egrave;tre le plus long possible qui sera utilis&eacute;.</p>

<p>Si vous d&eacute;sirez ins&eacute;rer une valeur dans une cha&icirc;ne, il est conseill&eacute;
de l'entourer d'accolades afin d'&eacute;viter toute confusion :</p>

<highlight language="config">
&lt;Macro DocRoot ${docroot}&gt;
    DocumentRoot /var/www/${docroot}/htdocs
&lt;/Macro&gt;
</highlight>

</section>

<section id="examples">
<title>Exemples</title>

<section>
<title>D&eacute;finition de serveurs virtuels</title>

<p>Un exemple typique d'utilisation de <module>mod_macro</module> est la
cr&eacute;ation dynamique de serveurs virtuels.</p>

<highlight language="config">
## D&eacute;finition d'une macro VHost pour les configurations r&eacute;p&eacute;titives

&lt;Macro VHost $host $port $dir&gt;
  Listen $port
  &lt;VirtualHost *:$port&gt;

    ServerName $host
    DocumentRoot $dir

    # Racine des documents publique
    &lt;Directory $dir&gt;
      Require all granted
    &lt;/Directory&gt;

    # restriction d'acc&egrave;s au sous-r&eacute;pertoire intranet.
    &lt;Directory $dir/intranet&gt;
      Require ip 10.0.0.0/8
    &lt;/Directory&gt;
  &lt;/VirtualHost&gt;
&lt;/Macro&gt;

## Utilisation de la macro VHost avec diff&eacute;rents 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>Suppression d'une d&eacute;finition de macro</title>

<p>Il est recommand&eacute; de supprimer la d&eacute;finition d'une macro apr&egrave;s
l'avoir utilis&eacute;e. Ceci permet d'&eacute;viter les confusions au sein d'un
fichier de configuration complexe o&ugrave; des conflits entre noms de
variables peuvent survenir.</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 -->

<!-- Macro -->
<directivesynopsis type="section">
<name>Macro</name>
<description>D&eacute;finition d'une macro dans un fichier de configuration</description>
<syntax>
&lt;Macro <var>nom</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>La directive <directive>Macro</directive> permet de d&eacute;finir une macro
    dans un fichier de configuration Apache. Le premier argument est le nom
    de la macro, et les arguments suivants sont les param&egrave;tres. Il
    est de bon aloi de pr&eacute;fixer les noms des param&egrave;tres d'une macro
    avec un caract&egrave;re parmi '<code>$%@</code>', et d'&eacute;viter d'en faire
    de m&ecirc;me avec les noms de macros.
    </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>

<!-- Use -->
<directivesynopsis>
<name>Use</name>
<description>Utilisation d'une macro</description>
<syntax>Use <var>nom</var> [<var>valeur1</var> ... <var>valeurN</var>]
</syntax>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
</contextlist>

<usage>
    <p> La directive <directive>Use</directive> permet d'utiliser une macro.
    La macro consid&eacute;r&eacute;e est expans&eacute;e. Son nombre d'arguments doit &ecirc;tre &eacute;gal au
    nombre de param&egrave;tres pr&eacute;cis&eacute;s dans sa d&eacute;finition. Les valeurs pass&eacute;es en
    argument sont attribu&eacute;es aux param&egrave;tres correspondants et
    substitu&eacute;es avant l'interpr&eacute;tation du texte de la macro.</p>

    <highlight language="config">
Use LocalAccessPolicy
...
Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"
    </highlight>

    <p>est &eacute;quivalent, avec les macros d&eacute;finies ci-dessus &agrave; :</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>

<!-- UndefMacro -->
<directivesynopsis>
<name>undefMacro</name>
<description>Supprime une macro</description>

<syntax>UndefMacro <var>nom</var></syntax>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
</contextlist>

<usage>
    <p>La directive <directive>UndefMacro</directive> annule la d&eacute;finition
    d'une macro qui doit avoir &eacute;t&eacute; d&eacute;finie auparavant.</p>

    <highlight language="config">
UndefMacro LocalAccessPolicy
UndefMacro RestrictedAccessPolicy
    </highlight>
</usage>
</directivesynopsis>

</modulesynopsis>