Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

# Module Apache mod_macro

Description: | Ce module permet d'utiliser des macros dans les fichiers de configuration Apache.
Statut: | Base
Identificateur de Module: | macro_module
Fichier Source: | mod_macro.c

### Sommaire

Ce module permet d'utiliser des macros dans les fichiers de configuration à l'exécution du serveur HTTP Apache afin de faciliter la création de nombreux blocs de configuration similaires. Quand le serveur démarre, les macros sont exécutées avec les paramètres fournis, et le résultat obtenu est traité au même titre que le reste du fichier de configuration.

### Sujets

- Utilisation
- Conseils
- Exemples

### Directives

### Traitement des bugs

- Journal des modifications de httpd
- Problèmes connus
- Signaler un bug

## Utilisation

On définit une macro à l'aide des blocs `<Macro>` qui contiennent la portion de votre configuration qui intervient de manière répétitive, y compris les variables pour les parties qui devront être substituées.

Par exemple, vous pouvez utiliser une macro pour définir un bloc `<VirtualHost>`, afin de pouvoir définir de nombreux serveurs virtuels similaires :

    <Macro VHost $name $domain>
    <VirtualHost *:80>
        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
    </VirtualHost>
    </Macro>

Comme les directives de configuration httpd, les noms des macros sont insensibles à la casse, à la différence des variables qui y sont, elles, sensibles.

Vous pouvez alors invoquer cette macro autant de fois que vous le voulez pour créer des serveurs virtuels

    Use VHost example example.com
    Use VHost myhost hostname.org
    Use VHost apache apache.org

    UndefMacro VHost

Au démarrage du serveur, chacune de ces invocations `Use` sera remplacée par une définition de serveur virtuel complète, comme décrit dans la définition de la `<Macro>`.

La directive `UndefMacro` permet d'éviter les conflits de définitions qui pourraient provenir de l'utilisation ultérieure de macros contenant les mêmes noms de variables.

Vous trouverez une version plus élaborée de cet exemple plus loin dans la section Exemples.

## Conseils

Les noms de paramètres doivent commencer par un sigil tel que `$`, `%`, ou `@`, de façon à ce qu'ils soient clairement identifiables, mais aussi afin de faciliter les interactions avec les autres directives, comme la directive de base `Define`. Dans le cas contraire, vous recevrez un avertissement. En tout état de cause, il est conseillé d'avoir une bonne connaissance globale de la configuration du serveur, afin d'éviter la réutilisation des mêmes variables à différents niveaux, ce qui peut être à l'origine de confusions.

Les paramètres préfixés par `$` ou `%` ne sont pas échappés. Les paramètres préfixés par `@` sont échappés entre guillemets.

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

Si vous désirez insérer une valeur dans une chaîne, il est conseillé de l'entourer d'accolades afin d'éviter toute confusion :

    <Macro DocRoot ${docroot}>
        DocumentRoot "/var/www/${docroot}/htdocs"
    </Macro>

## Exemples

### Définition de serveurs virtuels

Un exemple typique d'utilisation de `mod_macro` est la création dynamique de serveurs virtuels.

    ## Définition d'une macro VHost pour les configurations répétitives

    <Macro VHost $host $port $dir>
      Listen $port
      <VirtualHost *:$port>

        ServerName $host
        DocumentRoot "$dir"

        # Racine des documents publique
        <Directory "$dir">
          Require all granted
        </Directory>

        # restriction d'accès au sous-répertoire intranet.
        <Directory "$dir/intranet">
          Require ip 10.0.0.0/8
        </Directory>
      </VirtualHost>
    </Macro>

    ## Utilisation de la macro VHost avec diffé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

### Suppression d'une définition de macro

Il est recommandé de supprimer la définition d'une macro après l'avoir utilisée. Ceci permet d'éviter les confusions au sein d'un fichier de configuration complexe où des conflits entre noms de variables peuvent survenir.

    <Macro DirGroup $dir $group>
      <Directory "$dir">
        Require group $group
      </Directory>
    </Macro>

    Use DirGroup /www/apache/private private
    Use DirGroup /www/apache/server  admin

    UndefMacro DirGroup

## Directive <Macro>

Description: | Définition d'une macro dans un fichier de configuration
Syntaxe: | `<Macro nom [par1 .. parN]> ... </Macro>`
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_macro

La directive `<Macro>` permet de dé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ètres. Il est de bon aloi de préfixer les noms des paramètres d'une macro avec un caractère parmi '`$%@`', et d'éviter d'en faire de même avec les noms de macros.

    <Macro LocalAccessPolicy>
      Require ip 10.2.16.0/24
    </Macro>

    <Macro RestrictedAccessPolicy $ipnumbers>
       Require ip $ipnumbers
    </Macro>

## Directive UndefMacro

Description: | Supprime une macro
Syntaxe: | `UndefMacro nom`
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_macro

La directive `UndefMacro` annule la définition d'une macro qui doit avoir été définie auparavant.

    UndefMacro LocalAccessPolicy
    UndefMacro RestrictedAccessPolicy

## Directive Use

Description: | Utilisation d'une macro
Syntaxe: | `Use nom [valeur1 ... valeurN]`
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_macro

La directive `Use` permet d'utiliser une macro. La macro considérée est expansée. Son nombre d'arguments doit être égal au nombre de paramètres précisés dans sa définition. Les valeurs passées en argument sont attribuées aux paramètres correspondants et substituées avant l'interprétation du texte de la macro.

    Use LocalAccessPolicy
    ...
    Use RestrictedAccessPolicy "192.54.172.0/24 192.54.148.0/24"

est équivalent, avec les macros définies ci-dessus à :

    Require ip 10.2.16.0/24
    ...
    Require ip 192.54.172.0/24 192.54.148.0/24