Serveur HTTP Apache Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

# Module Apache mod_alias

Description: | Permet d'atteindre différentes parties du système de fichiers depuis l'arborescence des documents du site web, ainsi que la redirection d'URL
Statut: | Base
Identificateur de Module: | alias_module
Fichier Source: | mod_alias.c

### Sommaire

Les directives fournies par ce module permettent de manipuler et de contrôler les URLs à l'arrivée des requêtes sur le serveur. Les directives `Alias` et `ScriptAlias` permettent de faire correspondre des URLs avec des chemins du système de fichiers. Ceci permet de servir des contenus qui ne sont pas situés dans l'arborescence de `DocumentRoot` comme s'ils y étaient réellement. La directive `ScriptAlias` a pour effet supplémentaire de marquer le répertoire cible comme conteneur de scripts CGI.

Les directives `Redirect` indiquent aux clients qu'ils doivent effectuer une nouvelle requête avec une URL différente. Elles sont souvent utilisées lorsqu'une ressource a été déplacée.

Lorsque les directives `Alias`, `ScriptAlias` ou `Redirect` sont définies au sein d'une section `<Location>` ou `<LocationMatch>`, vous pouvez utiliser la syntaxe des expressions pour manipuler l'URL ou le chemin de destination.

`mod_alias` est conçu pour traiter des tâches simples de manipulation d'URL. Pour des tâches plus complexes comme la manipulation des chaînes d'arguments des requêtes, utilisez plutôt les outils fournis par le module `mod_rewrite`

### Sujets

- Chronologie du traitement

### Directives

### Traitement des bugs

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

### Voir aussi

- `mod_rewrite`
- Mise en correspondance des URLs avec le système de fichiers

## Chronologie du traitement

Les alias et redirections apparaissant dans différents contextes sont traités comme les autres directives en respectant les règles de fusion standards. Par contre, ils sont traités selon une chronologie particulière lorsqu'ils apparaissent dans le même contexte (par exemple, dans la même section `<VirtualHost>`).

Premièrement, toutes les redirections sont traitées avant les alias, et ainsi, une requête qui correspond à une directive `Redirect` ou `RedirectMatch` ne se verra jamais appliquer d'alias. Deuxièmement, les alias et redirections sont traités selon l'ordre dans lequel ils apparaissent dans le fichier de configuration, seule la première correspondance étant prise en compte.

Ainsi, lorsqu'une ou plusieurs de ces directives s'appliquent au même sous-répertoire, vous devez classer les chemins du plus précis au moins précis afin que toutes les directives puissent éventuellement s'appliquer, comme dans l'exemple suivant :

    Alias "/foo/bar" "/baz"
    Alias "/foo" "/gaq"

Si l'ordre des directives était inversé, la directive `Alias` ayant pour argument `/foo` serait toujours appliquée avant la directive `Alias` ayant pour argument `/foo/bar`, et cette dernière serait toujours ignorée.

La définition de directives `Alias`, `ScriptAlias` ou `Redirect` au sein de sections `<Location>` ou `<LocationMatch>` l'emporte sur d'autres définitions éventuelles de ces mêmes directives au niveau de la configuration générale du serveur.

## Directive Alias

Description: | Met en correspondance des URLs avec des chemins du système de fichiers
Syntaxe: | `Alias [chemin URL] chemin fichier|chemin répertoire`
Contexte: | configuration globale, serveur virtuel
Statut: | Base
Module: | mod_alias

La directive `Alias` permet de stocker des documents (destinés à être servis) dans des zones du système de fichiers situées en dehors de l'arborescence du site web `DocumentRoot`. Les URLs dont le chemin (décodé avec caractères %) commence par chemin URL seront mises en correspondance avec des fichiers locaux dont le chemin commence par chemin répertoire. Le chemin URL est sensible à la casse, même sur les systèmes de fichiers insensibles à la casse.

    Alias "/image" "/ftp/pub/image"

Une requête pour `http://example.com/image/foo.gif` fera renvoyer par le serveur le fichier `/ftp/pub/image/foo.gif`. Seuls les éléments de chemin complets sont testés ; ainsi l'alias précédent ne conviendra pas pour une requête du style `http://example.com/imagefoo.gif`. Pour des mises en correspondance plus complexes faisant intervenir les expressions rationnelles, veuillez vous reporter à la directive `AliasMatch`.

Notez que si vous ajoutez un slash de fin au chemin URL, vous devrez aussi ajouter un slash de fin au chemin de la requête. Autrement dit, si vous définissez

    Alias "/icons/" "/usr/local/apache/icons/"

l'alias précédent ne s'appliquera pas à l'URL `/icons` à cause de l'absence du slash final. Ainsi, si le slash final est absent du chemin de l'URL, il doit aussi l'être du chemin du fichier.

Notez qu'il pourra s'avérer nécessaire de définir des sections `<Directory>` supplémentaires qui couvriront la destination des alias. Le traitement des alias intervenant avant le traitement des sections `<Directory>`, seules les cibles des alias sont affectées (Notez cependant que les sections `<Location>` sont traitées avant les alias, et s'appliqueront donc).

En particulier, si vous créez un alias ayant pour cible un répertoire situé en dehors de l'arborescence de votre site web `DocumentRoot`, vous devrez probablement permettre explicitement l'accès à ce répertoire.

    Alias "/image" "/ftp/pub/image"
    <Directory "/ftp/pub/image">
        Require all granted
    </Directory>

Le nombre de slashes dans le paramètre chemin URL doit correspondre au nombre de slashes dans le chemin URL de la requête.

Si la directive `Alias` est définie au sein d'une section `<Location>` ou `<LocationMatch>`, chemin URL est omis et chemin fichier est interprété en utilisant la syntaxe des expressions.
Cette syntaxe est disponible à partir de la version 2.4.19 du serveur HTTP Apache.

    <Location "/image">
        Alias "/ftp/pub/image"
    </Location>
    <LocationMatch "/error/(?<NUMBER>[0-9]+)">
        Alias "/usr/local/apache/errors/%{env:MATCH_NUMBER}.html"
    </LocationMatch>

Notez que lorsque la directive `AliasPreservePath` est à "on", la destination contient le chemin entier, alors que lorsque la directive `AliasPreservePath` est à "off", tous les URLs sont associés à l'URL cible unique.

    # /files/foo et /files/bar associés à /ftp/pub/files/foo et /ftp/pub/files/bar
    <Location "/files">
        AliasPreservePath on
        Alias "/ftp/pub/files"
    </Location>
    # /errors/foo et /errors/bar associés à /var/www/errors.html
    <Location "/errors">
        AliasPreservePath off
        Alias "/var/www/errors.html"
    </Location>

## Directive AliasMatch

Description: | Met en correspondance des URLs avec le système de fichiers en faisant intervenir les expressions rationnelles
Syntaxe: | `AliasMatch regex chemin fichier|chemin répertoire`
Contexte: | configuration globale, serveur virtuel
Statut: | Base
Module: | mod_alias

Cette directive est identique à la directive `Alias`, mais fait appel aux expressions rationnelles, à la place d'une simple mise en correspondance de préfixe. L'expression rationnelle fournie est mise en correspondance avec le chemin URL, et si elle correspond, le serveur va substituer toute partie de chemin correspondant à l'expression entre parenthèses dans la chaîne fournie et l'utiliser comme nom de fichier. Par exemple, pour activer le répertoire `/icons`, on peut utiliser :

    AliasMatch "^/icons(.*)" "/usr/local/apache/icons$1$2"

Toute la puissance des expressions rationnelles peut être mise à contribution. Par exemple, il est possible de construire un alias avec un modèle de chemin URL insensible à la casse :

    AliasMatch "(?i)^/image(.*)" "/ftp/pub/image$1"

Il existe une différence subtile entre `Alias` et `AliasMatch` : `Alias` copie automatiquement toute portion supplémentaire de l'URI située après la partie du modèle qui correspond, à la fin du chemin du fichier de la partie droite, alors que `AliasMatch` ne le fait pas. Cela signifie qu'il sera préférable dans la plupart des cas de comparer l'expression rationnelle du modèle à la totalité de l'URI de la requête, et d'utiliser les substitutions dans la partie droite.

En d'autres termes, le remplacement d'`Alias` par `AliasMatch` ne produira pas le même résultat. Au minimum, vous devez ajouter `^` au début de l'expression rationnelle, `(.*)$` à sa fin et `$1` à la fin de la chaîne de remplacement.

Par exemple, supposons que nous voulions reformuler cet alias avec AliasMatch :

    Alias "/image/" "/ftp/pub/image/"

Le simple remplacement d'Alias par AliasMatch ne produira pas le même résultat. Ainsi, ce qui suit va rediriger toutes les requêtes qui contiennent /image/ vers /ftp/pub/image/ :

    AliasMatch "/image/" "/ftp/pub/image/"

Voici la directive AliasMatch qui produira le même résultat que la directive Alias ci-dessus :

    AliasMatch "^/image/(.*)$" "/ftp/pub/image/$1"

Bien entendu, il n'y a aucune raison d'utiliser `AliasMatch` dans le cas où `Alias` suffit. `AliasMatch` vous permet d'effectuer des choses beaucoup plus sophistiquées. Par exemple, vous pouvez servir différentes sortes de fichiers à partir de répertoires différents :

          AliasMatch "^/image/(.*)\.jpg$" "/fichiers/jpg.images/$1.jpg"
          AliasMatch "^/image/(.*)\.gif$" "/fichiers/gif.images/$1.gif"

Les éventuels slashes de tête multiples seront supprimés par le serveur avant que les directives de ce module n'effectuent des comparaisons avec le chemin URL de la requête.

## Directive AliasPreservePath

Description: | Associer le chemin entier à l'alias dans une section location.
Syntaxe: | `AliasPreservePath OFF|ON`
Défaut: | `AliasPreservePath OFF`
Contexte: | configuration globale, serveur virtuel, répertoire
Statut: | Base
Module: | mod_alias
Compatibilité: | Disponible à partir de la version 2.4.58 du serveur HTTP Apache.

Lorsqu'on utilise la version à deux paramètres de la directive `Alias`, le chemin complet après l'alias est préservé. Lorsqu'on utilise la version à un paramètre de la directive `Alias` dans une section `Location`, le chemin entier est supprimé, et tous les URLs sont associés à l'expression cible.

Pour que la version à un paramètre de la directive `Alias` préserve les chemins de la même façon que la version à deux paramètres, activez cette directive.

## Directive Redirect

Description: | Envoie une redirection externe demandant au client d'effectuer une autre requête avec une URL différente
Syntaxe: | `Redirect [état] [URL-path] URL`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_alias

La directive `Redirect` permet de faire correspondre une ancienne URL à une nouvelle en demandant au client d'aller chercher la ressource à une autre localisation.

L'ancien URL-path est un chemin sensible à la casse (décodé à l'aide de caractères %) commençant par un slash. Les chemins relatifs ne sont pas autorisés.

La nouvelle URL peut être une URL absolue commençant par un protocole et un nom d'hôte, mais on peut aussi utiliser un chemin URL commençant par un slash, auquel cas le protocole et le nom d'hôte du serveur local seront ajoutés.

Ensuite, toute requête commençant par URL-path va renvoyer une redirection au client vers l'URL cible. Tout élément de chemin supplémentaire situé en aval du URL-path sera ajouté à l'URL cible.

    # Redirige vers une URL sur un serveur différent
    Redirect "/service" "http://foo2.example.com/service"

    # Redirige vers une URL sur le même serveur
    Redirect "/one" "/two"

Si le client effectue une requête pour l'URL `http://example.com/service/foo.txt`, il lui sera demandé d'en effectuer une autre pour l'URL `http://foo2.example.com/service/foo.txt`. Ceci concerne les requêtes avec paramètres `GET`, comme `http://example.com/service/foo.pl?q=23&a=42`, qui seront redirigées vers `http://foo2.example.com/service/foo.pl?q=23&a=42`. Notez que les `POST`s seront ignorés.
Seuls les éléments de chemin complets sont testés, si bien que l'exemple précédent ne s'appliquera pas à l'URL `http://example.com/servicefoo.txt`. Pour des mises en correspondance plus complexes utilisant la syntaxe des expressions, ne spécifiez pas d'argument URL-path comme décrit ci-dessous. En outre, pour une mise en correspondance en utilisant les expressions rationnelles, veuillez vous reporter à la directive `RedirectMatch`.

### Note

Les directives `Redirect` ont priorité sur les directives `Alias` et `ScriptAlias`, quel que soit leur ordre d'apparition dans le fichier de configuration. Les directives `Redirect` définies au sein d'une section Location l'emportent sur les directives `Redirect` et `Alias` comportant un argument URL-path.

Si aucun argument état n'est spécifié, la redirection sera temporaire (code HTTP 302). Le client est alors informé que la ressource a été temporairement déplacée. On peut utiliser l'argument état pour renvoyer d'autres codes HTTP :

permanent
  Renvoie un code de redirection permanente (301), indiquant que la ressource a été définitivement déplacée.
temp
  Renvoie un code de redirection temporaire (302). C'est le comportement par défaut.
seeother
  Renvoie un code "See Other" (303) indiquant que la ressource a été remplacée par une autre.
gone
  Renvoie un code "Gone" (410) indiquant que la ressource a été définitivement supprimée. Lorsque ce code est utilisé, on ne doit pas utiliser l'argument URL.

On peut renvoyer d'autres codes en spécifiant le code numérique comme valeur de l'argument of état. Si le code est compris entre 300 et 399, l'argument URL doit être présent. Si le code n'est pas compris entre 300 et 399, l'argument URL ne doit pas apparaître. Le code doit être un code HTTP valide, connu du serveur HTTP Apache (voir la fonction `send_error_response` dans http_protocol.c).

    Redirect permanent "/one" "http://example.com/two"
    Redirect 303 "/three" "http://example.com/other"

Si une directive `Redirect` est définie au sein d'une section `<Location>` ou `<LocationMatch>` et si l'argument URL-path est omis, l'argument URL sera interprété en utilisant la syntaxe des expressions.
Cette syntaxe est disponible à partir de la version 2.4.19 du serveur HTTP Apache.

    <Location "/one">
        Redirect permanent "http://example.com/two"
    </Location>
    <Location "/three">
        Redirect 303 "http://example.com/other"
    </Location>
    <LocationMatch "/error/(?<NUMBER>[0-9]+)">
        Redirect permanent "http://example.com/errors/%{env:MATCH_NUMBER}.html"
    </LocationMatch>

## Directive RedirectMatch

Description: | Envoie une redirection externe faisant appel aux expressions rationnelles pour la mise en correspondance de l'URL courante
Syntaxe: | `RedirectMatch [état] regex URL`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_alias

Cette directive est identique à la directive `Redirect`, mais fait appel aux expressions rationnelles, à la place d'une simple mise en correspondance de préfixe. L'expression rationnelle fournie est mise en correspondance avec le chemin URL, et si elle correspond, le serveur va substituer toute partie de chemin correspondante entre parenthèses dans la chaîne spécifiée et l'utiliser comme nom de fichier. Par exemple, pour rediriger tous les fichiers GIF vers les fichiers JPEG de même nom sur un autre serveur, on peut utiliser :

    RedirectMatch "(.*)\.gif$" "http://autre.example.com$1.jpg"

Les remarques à propos de la différence entre `Alias` et `AliasMatch` s'appliquent aussi à la différence entre les directives `Redirect` et `RedirectMatch`. Voir la directive `AliasMatch` pour plus de détails.

## Directive RedirectPermanent

Description: | Envoie une redirection externe permanente demandant au client d'effectuer une nouvelle requête avec une URL différente
Syntaxe: | `RedirectPermanent chemin URL URL`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_alias

Cette directive informe le client que la redirection est permanente (code 301). Son comportement est exactement le même que celui de `Redirect permanent`.

## Directive RedirectRelative

Description: | Redirection relative de cibles.
Syntaxe: | `RedirectRelative On|Off`
Défaut: | `RedirectRelative Off`
Contexte: | configuration globale, serveur virtuel, répertoire
Statut: | Base
Module: | mod_alias
Compatibilité: | Disponible à partir de la version 2.4.58 du serveur HTTP Apache

Par défaut, si l'URL cible d'une directive `Redirect` est une URL relative commençant par un caractère '/', le serveur convertit cette dernière en URL absolue avant de répondre au client. En définissant `RedirectRelative` à "On", l'URL relative est présentée au client sans modification.

## Directive RedirectTemp

Description: | Envoie une redirection externe temporaire demandant au client d'effectuer une nouvelle requête avec une URL différente
Syntaxe: | `RedirectTemp chemin URL URL`
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées: | FileInfo
Statut: | Base
Module: | mod_alias

Cette directive informe le client que la redirection n'est que temporaire (code 302). Son comportement est exactement le même que celui de `Redirect temp`.

## Directive ScriptAlias

Description: | Fait correspondre une URL à une zone du système de fichiers et désigne la cible comme script CGI
Syntaxe: | `ScriptAlias [chemin URL] chemin fichier|chemin répertoire`
Contexte: | configuration globale, serveur virtuel, répertoire
Statut: | Base
Module: | mod_alias

La directive `ScriptAlias` présente le même comportement que la directive `Alias`, mais désigne en plus le répertoire cible comme conteneur de scripts CGI qui seront traitées par le gestionnaire cgi-script du module `mod_cgi`. Les URLs dont le chemin URL sensible à la casse (décodé avec caractères %) commence par chemin URL seront mises en correspondance avec les scripts dont le chemin commence par le second argument, qui est un chemin complet dans le système de fichiers local.

    ScriptAlias "/cgi-bin/" "/web/cgi-bin/"

Une requête pour `http://example.com/cgi-bin/foo` ferait exécuter par le serveur le script `/web/cgi-bin/foo`. Cette configuration est sensiblement équivalente à :

    Alias "/cgi-bin/" "/web/cgi-bin/"
    <Location "/cgi-bin">
        SetHandler cgi-script
        Options +ExecCGI
    </Location>

Vous pouvez aussi utiliser `ScriptAlias` avec un script ou gestionnaire de votre cru. Par exemple :

    ScriptAlias "/cgi-bin/" "/web/cgi-handler.pl"

Dans ce scénario, tous les fichiers faisant l'objet d'une requête dans `/cgi-bin/` seront traités par le fichier que vous avez spécifié, ce qui vous permet d'utiliser votre propre gestionnaire. Vous pouvez l'utiliser comme enveloppe (wrapper) pour les scripts CGI afin d'ajouter du contenu, ou autre action "maison".

Il est préférable d'éviter de placer les scripts CGI dans l'arborescence de `DocumentRoot` afin d'éviter de révéler accidentellement leur code source lors d'une modification de configuration. On y parvient aisément avec `ScriptAlias` en mettant en correspondance une URL et en désignant la cible comme scripts CGI par la même occasion. Si vous choisissez de placer vos scripts CGI dans un répertoire accessible depuis le web, n'utilisez pas `ScriptAlias`. Utilisez plutôt `<Directory>`, `SetHandler`, et `Options` comme dans l'exemple suivant :

    <Directory "/usr/local/apache2/htdocs/cgi-bin">
        SetHandler cgi-script
        Options ExecCGI
    </Directory>

Ceci est nécessaire car plusieurs chemins URL peuvent correspondre à la même zone du système de fichiers, court-circuitant ainsi la directive `ScriptAlias` et révélant le code source des scripts CGI s'ils ne sont pas protégés par une section `Directory`.

Si la directive `ScriptAlias` est définie au sein d'une section `<Location>` ou `<LocationMatch>` et si l'argument chemin URL est omis, l'argument URL sera interprété en utilisant la syntaxe des expressions.
Cette syntaxe est disponible à partir de la version 2.4.19 du serveur HTTP Apache.

    <Location "/cgi-bin">
        ScriptAlias "/web/cgi-bin/"
    </Location>
    <LocationMatch "/cgi-bin/errors/(?<NUMBER>[0-9]+)">
        ScriptAlias "/web/cgi-bin/errors/%{env:MATCH_NUMBER}.cgi"
    </LocationMatch>

### Voir aussi

- Tutoriel CGI

## Directive ScriptAliasMatch

Description: | Fait correspondre une URL à une zone du système de fichiers en faisant appel aux expressions rationnelles et en désignant la cible comme un script CGI
Syntaxe: | `ScriptAliasMatch regex chemin fichier|chemin répertoire`
Contexte: | configuration globale, serveur virtuel
Statut: | Base
Module: | mod_alias

Cette directive est équivalente à la directive `ScriptAlias`, mais fait appel aux expressions rationnelles, à la place d'une simple mise en correspondance de préfixe. L'expression rationnelle fournie est mise en correspondance avec le chemin URL, et si elle correspond, le serveur va substituer toute partie de chemin entre parenthèses dans la chaîne spécifiée et l'utiliser comme nom de fichier. Par exemple, pour activer le répertoire standard `/cgi-bin`, on peut utiliser :

    ScriptAliasMatch "^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"

Comme dans le cas d'AliasMatch, toute la puissance des expressions rationnelles peut être mise à contribution. Par exemple, il est possible de construire un alias avec une comparaison du modèle du chemin URL insensible à la casse :

    ScriptAliasMatch "(?i)^/cgi-bin(.*)" "/usr/local/apache/cgi-bin$1"

Les remarques à propos de la différence entre `Alias` et `AliasMatch` s'appliquent aussi à la différence entre les directives `ScriptAlias` et `ScriptAliasMatch`. Voir la directive `AliasMatch` pour plus de détails.