Documentation du Serveur HTTP Apache Version 2.4 - Serveur Apache HTTP Version 2.4

Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation

Documentation du Serveur HTTP Apache Version 2.4

Notes de version

  • Nouvelles fonctionnalités dApache 2.3/2.4
  • Nouvelles fonctionnalités d'Apache 2.1/2.2
  • Nouvelles fonctionnalités d'Apache 2.0
  • Mise à jour de la version 2.2 vers la version 2.4
  • Licence Apache

Manuel de référence

  • Compilation et installation
  • Démarrage
  • Arrêt ou redémarrage
  • Directives de configuration à l'exécution
  • Modules
  • Modules multi-processus (MPMs)
  • Filtres
  • Gestionnaires
  • Interpréteur d'expressions
  • Index des directives disponibles dans les fichiers .htaccess
  • Le serveur et ses utilitaires
  • Glossaire

Guide de l'utilisateur

  • Bien démarrer
  • Ecoute sélective
  • Fichiers de configuration
  • Sections de configuration
  • Mise en cache du contenu
  • Négociation sur le contenu
  • Objets Dynamiques Partagés (DSO)
  • Variables d'environnement
  • Fichiers de traces
  • Mise en correspondance des URLs avec le système de fichiers
  • Optimisation des performances
  • Conseils sur la sécurité
  • Configuration à l'échelle du serveur
  • Chiffrement SSL/TLS
  • Exécution des CGI avec suexec
  • Réécriture des URLs avec mod_rewrite
  • Hôtes virtuels

Recettes / Tutoriels

  • Authentification et autorisation
  • Contrôle d'accès
  • CGI: Contenu dynamique
  • Fichiers .htaccess
  • Server Side Includes (SSI)
  • Répertoires Web des utilisateurs (public_html)
  • Guide de configuration des mandataires inverses
  • Guide HTTP/2

Notes spécifiques aux différentes plateformes

  • Microsoft Windows
  • Systèmes basés sur les paquet RPM (Redhat / CentOS / Fedora)
  • Novell NetWare
  • Portage EBCDIC

Autres sujets

  • Foire Aux Questions
  • Plan du site
  • Documentation du développeur
  • Aide pour la documentation
  • Autres notes
  • Wiki

Copyright 2018 The Apache Software Foundation.
Autorisé sous Apache License, Version 2.0.


Mise à jour de la version 2.2 vers la version 2.4 - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Mise à jour de la version 2.2 vers la version 2.4

Afin d'assister les utilisateurs lors de leurs opérations de mise à jour, nous maintenons un document qui comporte des informations critiques à l'attention des personnes qui utilisent déjà le serveur HTTP Apache. Ces informations ne sont que de brèves notes, et vous trouverez plus d'informations dans le document Nouvelles fonctionnalités, ou dans le fichier src/CHANGES. Les développeurs d'applications et de modules trouveront un résumé des modifications de l'API dans la vue d'ensemble Mises à jour de l'API.

Ce document présente les changements de comportement du serveur qui peuvent nécessiter une modification de la configuration, et une méthode pour utiliser la version 2.4 du serveur en parallèle avec la version 2.2. Pour tirer parti des nouvelles fonctionnalités de la version 2.4, reportez-vous au document "Nouvelles fonctionnalités".

Ce document ne décrit que les modifications intervenues entre les versions 2.2 et 2.4. Si vous effectuez une mise à jour depuis la version 2.0, vous devez aussi consulter le document de mise à jour de 2.0 vers 2.2.

Voir aussi

  • Vue d'ensemble des nouvelles fonctionnalités du serveur HTTP Apache 2.4

Modifications des paramètres de compilation

Le processus de compilation est très similaire à celui de la version 2.2. Dans la plupart des cas, vous pourrez utiliser votre ancienne ligne de commande configure (telle qu'elle est enregistrée dans le fichier build/config.nice situé dans le répertoire de compilation du serveur). Voici certains changements intervenus dans la configuration par défaut :

  • Les modules suivants ont été supprimés : mod_authn_default, mod_authz_default et mod_mem_cache. Si vous utilisiez mod_mem_cache sous la version 2.2, vous devez maintenant utiliser mod_cache_disk dans la version 2.4.
  • Toutes les implémentations de répartition de charge ont été déplacées vers des sous-modules spécifiques de mod_proxy, comme mod_lbmethod_bybusyness. Vous devrez compiler et chargés tous les modules correspondants que votre configuration utilise.
  • Le support de BeOS, TPF, et des anciennes plates-formes telles que A/UX, Next, et Tandem a été supprimé, car elles ne sont plus considérées comme maintenues.
  • configure: les modules dynamiques (DSO) sont compilés par défaut
  • configure: par défaut, seul un jeu de modules de base est chargé. Les autres directives LoadModule sont mises en commentaires dans le fichier de configuration.
  • configure: le jeu de modules "most" est compilé par défaut
  • configure: le jeu de modules "reallyall" ajoute les modules de développeur au jeu "all".

Modifications de la configuration à l'exécution

Des changements significatifs dans la configuration de l'autorisation, ainsi que quelques changements mineurs, peuvent nécessiter une mise à jour des fichiers de configuration de la version 2.2 avant de les utiliser sous la version 2.4.

Autorisation

Tout fichier de configuration qui gère des autorisations devra probablement être mis à jour.

Vous devez vous reporter au document Authentification, autorisation et contrôle d'accès, et plus particulièrement à la section Pour aller plus loin qu'une simple autorisation qui explique les nouveaux mécanismes permettant de contrôler l'ordre dans lequel les directives d'autorisation sont appliquées.

Les directives qui contrôlent la manière dont les modules d'autorisation réagissent lorsqu'ils ne reconnaissent pas l'utilisateur authentifié ont été supprimées : elles comprennent les directives AuthzLDAPAuthoritative, AuthzDBDAuthoritative, AuthzDBMAuthoritative, AuthzGroupFileAuthoritative, AuthzUserAuthoritative et AuthzOwnerAuthoritative. Ces directives ont été remplacées par les directives plus explicites RequireAny, RequireNone, et RequireAll.

Si vous utilisez mod_authz_dbm, vous devez mettre à jour votre configuration en remplaçant les directives du style Require group ... par des directives du style Require dbm-group ....

Contrôle d'accès

Dans la version 2.2, le contrôle d'accès basé sur le nom d'hôte du client, son adresse IP, ou d'autres caractéristiques de la requête était assuré via les directives Order, Allow, Deny, et Satisfy.

Dans la version 2.4, ce contrôle d'accès est assuré, comme tout contrôle d'autorisation, par le nouveau module mod_authz_host. Bien que le module mod_access_compat soit fourni à des fins de compatibilité avec les anciennes configurations, les anciennes directives de contrôle d'accès devront être remplacées par les nouveaux mécanismes d'authentification.

Mélanger anciennes et nouvelles directives

Mélanger d'anciennes directives comme Order, Allow ou Deny avec des nouvelles comme Require est techniquement possible mais déconseillé. En effet, mod_access_compat a été conçu pour supporter des configurations ne contenant que des anciennes directives afin de faciliter le passage à la version 2.4. Les exemples ci-dessous vous permettront de vous faire une meilleure idée des problèmes qui peuvent survenir.

Voici quelques exemples de contrôle d'accès avec l'ancienne et la nouvelle méthode :

Dans cet exemple, il n'y a pas d'authentification et toutes les requêtes sont rejetées :

version 2.2 :

Order deny,allow
Deny from all

version 2.4 :

Require all denied

Dans cet exemple, il n'y a pas d'authentification et toutes les requêtes sont acceptées :

version 2.2 :

Order allow,deny
Allow from all

version 2.4 :

Require all granted

Dans l'exemple suivant, il n'y a pas d'authentification et tous les hôtes du domaine example.org ont l'autorisation d'accès, tous les autres étant rejetés :

version 2.2 :

Order Deny,Allow
Deny from all
Allow from example.org

version 2.4 :

Require host example.org

Dans l'exemple suivant, tous les hôtes du domaine example.org ont l'autorisation d'accès, tous les autres sont rejetés :

version 2.2 :

Order Deny,Allow
Deny from all
Allow from example.org

version 2.4 :

Require host example.org

Dans l'exemple suivant, le mélange d'anciennes et de nouvelles directives produit des résultats inattendus.

Mélange d'anciennes et de nouvelles directives : RESULTAT INATTENDU

DocumentRoot "/var/www/html"

<Directory "/">
    AllowOverride None
    Order deny,allow
    Deny from all
</Directory>

<Location "/server-status">
    SetHandler server-status
    Require local
</Location>

access.log - GET /server-status 403 127.0.0.1
error.log - AH01797: client denied by server configuration: /var/www/html/server-status

Pourquoi httpd interdit l'accès à server-status alors que la configuration semble l'autoriser ? Parce que dans ce scénario de fusion de configuration, les directives de mod_access_compat sont prioritaires par rapport à celles de mod_authz_host.

L'exemple suivant quant à lui produit un résultat conforme :

Mélange d'anciennes et de nouvelles directives : RESULTAT CONFORME

DocumentRoot "/var/www/html"

<Directory "/">
    AllowOverride None
    Require all denied
</Directory>

<Location "/server-status">
    SetHandler server-status
    Order deny,allow
    Deny from all
    Allow From 127.0.0.1
</Location>

access.log - GET /server-status 200 127.0.0.1

En conclusion, même si une configuration hybride peut fonctionner, essayez de l'éviter lors de la mise à jour : soit conservez les anciennes directives, puis migrez-les vers les nouvelles ultérieurement, soit effectuez une migration immédiate de toutes les anciennes directives vers les nouvelles.

Dans de nombreuses configurations avec authentification où la directive Satisfy était définie à sa valeur par défaut ALL, les lignes de configuration qui désactivent le contrôle d'accès basé sur l'hôte sont maintenant omises :

Version 2.2 :

# configuration en version 2.2 qui désactive le contrôle d'accès basé sur le nom
# d'hôte pour n'utiliser que l'authentification
Order Deny,Allow
Allow from all
AuthType Basic
AuthBasicProvider file
AuthUserFile /example.com/conf/users.passwd
AuthName secure
Require valid-user

Version 2.4 :

# Pas besoin de remplacer les directives de contrôle d'accès basées sur le nom
# d'hôte désactivées
AuthType Basic
AuthBasicProvider file
AuthUserFile /example.com/conf/users.passwd
AuthName secure
Require valid-user

Dans les configurations où l'authentification et le contrôle d'accès se combinaient dans un but précis, les directives de contrôle d'accès doivent être migrées. Dans l'exemple suivant, les requêtes qui correspondent aux deux critères sont acceptées :

Version 2.2 :

Order allow,deny
Deny from all
# ALL est la valeur par défaut de Satisfy
Satisfy ALL
Allow from 127.0.0.1
AuthType Basic
AuthBasicProvider file
AuthUserFile /example.com/conf/users.passwd
AuthName secure
Require valid-user

Version 2.4 :

AuthType Basic
AuthBasicProvider file
AuthUserFile /example.com/conf/users.passwd
AuthName secure
<RequireAll>
  Require valid-user
  Require ip 127.0.0.1
</RequireAll>

Dans les configurations où l'authentification et le contrôle d'accès se combinaient dans un but précis, les directives de contrôle d'accès doivent être migrées. Dans l'exemple suivant, les requêtes qui correspondent à au moins un critère sont acceptées :

Version 2.2 :

Order allow,deny
Deny from all
Satisfy any
Allow from 127.0.0.1
AuthType Basic
AuthBasicProvider file
AuthUserFile /example.com/conf/users.passwd
AuthName secure
Require valid-user

Version 2.4 :

AuthType Basic
AuthBasicProvider file
AuthUserFile /example.com/conf/users.passwd
AuthName secure
# Implicite : <RequireAny>
Require valid-user
Require ip 127.0.0.1

Autres changements dans la configuration

D'autres ajustements mineurs peuvent s'avérer nécessaires pour certaines configurations particulières, comme décrit ci-dessous.

  • La directive MaxRequestsPerChild a été renommée en MaxConnectionsPerChild; ce nouveau nom reflète mieux l'usage de cette directive. L'ancien nom est encore supporté.
  • La directive MaxClients a été renommée en MaxRequestWorkers; ce nouveau nom reflète mieux l'usage de cette directive. Pour les modules multiprocessus asynchrones, comme event, le nombre maximal de clients n'est pas équivalent au nombre de threads du worker. L'ancien nom est encore supporté.
  • La directive DefaultType ne produit plus aucun effet, si ce n'est d'émettre un avertissement si elle est définie à une valeur autre que none. D'autres directives de configuration la remplacent dans la version 2.4.
  • La valeur par défaut de la directive AllowOverride est maintenant None.
  • La valeur par défaut de la directive EnableSendfile est maintenant Off.
  • La valeur par défaut de la directive FileETag est maintenant "MTime Size" (sans INode).
  • mod_dav_fs: le format du fichier DavLockDB a changé pour les systèmes avec inodes. L'ancien fichier DavLockDB doit être supprimé dans le cadre de la mise à jour.
  • La directive KeepAlive n'accepte que les valeurs On ou Off. Avant, toute valeur autre que "Off" ou "0" était traitée comme "On".
  • Les directives AcceptMutex, LockFile, RewriteLock, SSLMutex, SSLStaplingMutex et WatchdogMutexPath ont été remplacées par la directive unique Mutex. Vous devez évaluer l'impact de ces directives obsolètes dans votre configuration version 2.2 afin de déterminer si elles peuvent être simplement supprimées, ou si elles doivent être remplacées par la directive Mutex.
  • mod_cache: la directive CacheIgnoreURLSessionIdentifiers effectue maintenant une correspondance exacte dans la chaîne de paramètres au lieu d'une correspondance partielle. Si votre configuration mettait en jeu des sous-chaînes comme sessionid pour correspondre à /une-application/image.gif;jsessionid=123456789, vous devez maintenant utiliser la chaîne de correspondance complète jsessionid.
  • mod_cache: le second paramètre de la directive CacheEnable ne concerne les contenus en mandat direct que s'ils débutent par le protocole approprié. Dans les versions 2.2 et antérieures, un paramètre tel que '/' concernait tous les contenus.
  • mod_ldap: la directive LDAPTrustedClientCert s'utilise maintenant exclusivement au sein d'une configuration de niveau répertoire. Si vous utilisez cette directive, passez en revue votre configuration pour vous assurer qu'elle est bien présente dans tous les contextes de répertoire nécessaires.
  • mod_filter: la syntaxe de la directive FilterProvider utilise maintenant une expression booléenne pour déterminer si un filtre s'applique.
  • mod_include:
    • L'élément #if expr utilise maintenant le nouvel interpréteur d'expressions. L'ancienne syntaxe peut être réactivée via la directive SSILegacyExprParser.
    • Dans la portée du répertoire, une directive de configuration SSI* ne provoque plus la réinitialisation à leur valeur par défaut de toutes les directives SSI* de niveau répertoire.
  • mod_charset_lite : l'option DebugLevel a été supprimée en faveur d'une configuration de la directive LogLevel au niveau répertoire.
  • mod_ext_filter : l'option DebugLevel a été supprimée en faveur d'une configuration de la directive LogLevel au niveau répertoire.
  • mod_proxy_scgi: certaines applications web ne fonctionneront plus correctement avec la nouvelle configuration de PATH_INFO qui est différente de celle de la version 2.2. La configuration précédente peut être restaurée en définissant la variable proxy-scgi-pathinfo.
  • mod_ssl: le contrôle de révocation des certificats basé sur les CRL doit être maintenant explicitement configuré via la directive SSLCARevocationCheck.
  • mod_substitute: la taille maximale d'une ligne est maintenant 1Mo.
  • mod_reqtimeout: si ce module est chargé, il définit maintenant certains temps d'attente par défaut.
  • mod_dumpio: la directive DumpIOLogLevel n'est plus supportée. Les données sont toujours enregistrées au niveau trace7 de LogLevel
  • Jusqu'à la version 2.2, sur les plateformes de style Unix, les commandes de redirection des logs définies via ErrorLog ou CustomLog étaient invoquées en utilisant /bin/sh -c. A partir de la version 2.4, les commandes de redirection des logs sont exécutées directement. Pour retrouver l'ancien comportement, voir la documentation sur la redirection des logs

Changements divers

  • mod_auto_index: extrait maintenant les titres et affiche la description pour les fichiers .xhtml qui étaient jusqu'alors ignorés.
  • mod_ssl : le format par défaut des variables *_DN a changé. Il est cependant encore possible d'utiliser l'ancien format via la nouvelle option LegacyDNStringFormat de la directive SSLOptions. Le protocole SSLv2 n'est plus supporté. Les directives SSLProxyCheckPeerCN et SSLProxyCheckPeerExpire sont maintenant définies par défaut à On, et les requêtes mandatées vers des serveurs HTTPS possèdant des certificats non conformes ou périmés échoueront donc avec un code d'erreur 502 (Bad gateway).
  • htpasswd utilise maintenant par défaut les condensés MD5 sur toutes les plates-formes.
  • La directive NameVirtualHost n'a plus aucun effet, si ce n'est l'émission d'un avertissement. Toute combinaison adresse/port apparaissant dans plusieurs serveurs virtuels est traitée implicitement comme un serveur virtuel basé sur le nom.
  • mod_deflate n'effectue plus de compression s'il s'aperçoit que la quantité de données ajoutée par la compression est supérieure à la quantité de données à compresser.
  • Les pages d'erreur multilingues de la version 2.2.x ne fonctionneront qu'après avoir été corrigées pour respecter la nouvelle syntaxe de l'élément #if expr= du module mod_include, ou si la directive SSILegacyExprParser a été activée pour le répertoire contenant les pages d'erreur.
  • La fonctionnalité fournie par mod_authn_alias dans les précédentes versions (en fait la directive AuthnProviderAlias) est maintenant fournie par mod_authn_core.
  • Les directives RewriteLog et RewriteLogLevel ont été supprimées. Leur fonctions sont maintenant assurées par la directive LogLevel qui permet de définir un niveau de journalisation approprié pour le module mod_rewrite. Voir aussi la section journalisation de mod_rewrite.

Modules tiers

Tous les modules tiers doivent être recompilés pour la version 2.4 avant d'être chargés.

De nombreux modules tiers conçus pour la version 2.2 fonctionneront sans changement avec le serveur HTTP Apache version 2.4. Certains nécessiteront cependant des modifications ; se reporter à la vue d'ensemble Mise à jour de l'API.

Problèmes de mise à jour courants

  • Erreurs au démarrage :
    • Invalid command 'User', perhaps misspelled or defined by a module not included in the server configuration - chargez le module mod_unixd
    • Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration, ou Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration - chargez le module mod_access_compat, ou mettez à jour vers la version 2.4 les directives d'autorisation.
    • Ignoring deprecated use of DefaultType in line NN of /path/to/httpd.conf - supprimez la directive DefaultType et remplacez-la par les directives de configuration appropriées.
    • Invalid command 'AddOutputFilterByType', perhaps misspelled or defined by a module not included in the server configuration - la directive AddOutputFilterByType qui était jusqu'alors implémentée par le module core, l'est maintenant par le module mod_filter, qui doit donc être chargé.
  • Erreurs de traitement des requêtes :
    • configuration error: couldn't check user: /path - chargez le module mod_authn_core.
    • Les fichiers .htaccess ne sont pas traités - Vérifiez la présence d'une directive AllowOverride appropriée ; sa valeur par défaut est maintenant None.


Vue d'ensemble des nouvelles fonctionnalités de la version 2.4 du serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Vue d'ensemble des nouvelles fonctionnalités de la version 2.4 du serveur HTTP Apache

Ce document décrit les modifications majeures apportées par la version 2.4 du serveur HTTP Apache. Pour les nouvelles fonctionnalités ajoutées par la version 2.2, se référer au document Nouvelles fonctionnalités de la version 2.2.

Améliorations du noyau

Modules multiprocessus (MPMs) chargeables à l'exécution
Plusieurs MPMs peuvent maintenant être compilés en tant que modules chargeables. Le choix du MPM à utiliser s'effectue à l'exécution via la directive LoadModule.
MPM Event
Le MPM Event n'en est plus au stade expérimental et est maintenant pleinement supporté.
Support du mode asynchrone
Le support des lectures/écritures asynchrones pour les MPMs et les plateformes qui l'implémentent a été amélioré.
Configuration du niveau de journalisation (LogLevel) par module et par répertoire
La directive LogLevel peut maintenant être définie par module et par répertoire. Les nouveaux niveaux trace1 à trace8 ont été ajoutés au dessus du niveau de journalisation debug.
Sections de configuration au niveau requête
Les sections If, <ElseIf> et <Else> permettent de définir une configuration en fonction de critères liés à la requête.
Interpréteur d'expressions à usage général
Un nouvel interpréteur d'expressions permet de spécifier des conditions complexes via des directives à syntaxe commune comme SetEnvIfExpr, RewriteCond, Header, <If>, etc...
KeepAliveTimeout en millisecondes
Il est maintenant possible de définir la directive KeepAliveTimeout en millisecondes.
Directive NameVirtualHost
Cette directive n'est plus nécessaire et est maintenant obsolète.
Directives autorisées dans les fichiers .htaccess
La nouvelle directive AllowOverrideList permet de contrôler de manière plus précise la liste des directives autorisées dans les fichiers .htaccess.
Variables dans les fichiers de configuration
La directive Define permet de définir des variables dans les fichiers de configuration, améliorant ainsi la clareté de la présentation si la même valeur est utilisée en plusieurs points de la configuration.
Diminution de la mémoire utilisée
Bien qu'elle propose de nombreuses nouvelles fonctionnalités, la version 2.4.x tend à utiliser moins de mémoire que la version 2.2.x.

Nouveau modules

mod_proxy_fcgi
Mise à disposition du protocole FastCGI pour mod_proxy.
mod_proxy_scgi
Mise à disposition du protocole SCGI pour mod_proxy.
mod_proxy_express
Ajoute à mod_proxy la configuration dynamique de mandataires inverses en masse.
mod_remoteip
Remplace l'adresse IP distante et le nom d'hôte apparents du client pour la requête courante par la liste d'adresses IP présentée par un mandataire ou un répartiteur de charge via les en-têtes de la requête.
mod_heartmonitor, mod_lbmethod_heartbeat
Permet à mod_proxy_balancer de répartir la charge en fonction du nombre de connexions actives sur les serveurs d'arrière-plan.
mod_proxy_html
Anciennement module tiers, il supporte la correction des liens HTML dans une situation de mandat inverse, où le serveur d'arrière-plan génère des URLs qui ne sont pas valides du point de vue des clients du mandataire.
mod_sed
Une amélioration de mod_substitute qui permet d'éditer le corps de la réponse avec toute la puissance de la commande sed.
mod_auth_form
Implémente une authentification à base de formulaire.
mod_session
Permet de conserver les données de sessions des clients sous forme de cookies ou dans une base de données.
mod_allowmethods
Permet de restreindre l'utilisation de certaines méthodes HTTP sans interférer avec l'authentification et l'autorisation.
mod_lua
Embarque le langage Lua dans httpd pour la configuration et les fonctions logiques courantes (Expérimental).
mod_log_debug
Permet d'introduire une journalisation personnalisée à différentes phases du traitement de la requête.
mod_buffer
Fournit un tampon pour les piles des filtres en entrée et en sortie.
mod_data
Convertit un corps de réponse en URL de type données RFC2397.
mod_ratelimit
Permet de limiter la bande passante pour certains clients.
mod_request
Fournit des filtres permettant de gérer et de mettre à disposition les corps des requêtes HTTP.
mod_reflector
Permet de renvoyer comme réponse le corps de la requête via la pile du filtre de sortie.
mod_slotmem_shm
Met à disposition un fournisseur de mémoire partagée à base de slots (du style tableau de bord).
mod_xml2enc
Anciennement module tiers, il supporte l'internationalisation dans les modules de filtrage basés sur libxml2 (support du markup)
mod_macro (disponible à partir de la version 2.4.5)
Permet d'utiliser des macros au sein des fichiers de configuration.
mod_proxy_wstunnel (disponible à partir de la version 2.4.5)
Support des tunnels web-socket.
mod_authnz_fcgi (disponible à partir de la version 2.4.10)
Permet aux applications d'autorisation FastCGI d'authentifier et/ou autoriser les clients.
mod_http2 (disponible à partir de la version 2.4.17)
Support de la couche transport HTTP/2.
mod_proxy_hcheck (disponible à partir de la version 2.4.21)
Support d'un bilan de santé dynamique indépendant pour les serveurs d'arrière-plan mandatés distants.

Améliorations des modules

mod_ssl
mod_ssl peut maintenant vérifier la validité des certificats clients en se connectant à un serveur OCSP. Il est possible de définir un répondeur par défaut, et de choisir si l'on préfère le répondeur désigné dans le certificat client.
En outre, mod_ssl supporte maintenant l'estampillage OCSP (OCSP stapling), qui permet au serveur d'attester la validité de son certificat auprès du client au cours de la phase de négociation de la connexion.
Enfin, mod_ssl peut maintenant être configuré pour que celui-ci partage les données de session SSL entre les serveurs via memcached.
Le support des clés EC a été ajouté à celui des clés RSA et DSA.
Support de TLS-SRP (disponible à partir de la version 2.4.4).
mod_proxy
La directive ProxyPass est maintenant configurée de manière optimale dans les sections Location ou LocationMatch, et offre un gain de performances important par rapport à la syntaxe traditionnelle à deux paramètres lorsqu'elle est présente en grand nombre.
Il est maintenant possible de configurer l'adresse source dans les requêtes mandatées.
Support des sockets de type Unix vers le serveur d'arrière-plan (disponible à partir de la version 2.4.7).
mod_proxy_balancer
Le gestionnaire de répartition de charge propose de nouvelles fonctionnalités. Ainsi, les possibilités de configuration des membres du groupe de répartition de charge pendant l'exécution ont été améliorées (possibilité d'ajout d'un membre supplémentaire).
Configuration à l'exécution d'un sous-ensemble de paramètres de répartition de charge.
Les membres du groupe de répartition peuvent être définis à 'Drain' de façon à ce qu'ils ne répondent qu'aux sessions persistantes existantes, ce qui permet de les mettre hors ligne en douceur.
Les règlages du répartiteur de charge peuvent être rendus persistants après redémarrage.
mod_cache
Le filtre CACHE du module mod_cache peut être inséré à un certain point de la chaîne de filtrage pour contrôler plus finement la mise en cache.
mod_cache peut maintenant mettre en cache des requêtes HEAD.
Chaque fois que cela est possible, les directives de mod_cache peuvent maintenant être définies au niveau du répertoire, et non plus seulement au niveau du serveur principal.
L'URL de base des URLs en cache peut être personnalisée de façon à ce qu'un cluster de caches puisse partager le même préfixe d'URL.
mod_cache peut maintenant servir du contenu non mis à jour lorsqu'un serveur d'arrière-plan n'est pas disponible (erreur 5xx).
mod_cache peut maintenant insérer HIT/MISS/REVALIDATE dans un en-tête X-Cache.
mod_include
Support de l'attribut 'onerror' dans un élément 'include', permettant de renvoyer un message d'erreur personnalisé à la place du message d'erreur par défaut.
mod_cgi, mod_include, mod_isapi, ...
La traduction des en-têtes en variables d'environnement est plus stricte qu'avant, ce qui permet de diminuer l'exposition aux attaques de type cross-site-scripting via injection d'en-têtes. Les en-têtes contenant des caractères invalides (comme les caractères de soulignement) sont maintenant ignorés. Le document Les variables d'environnement dans Apache présente quelques pistes pour contourner ce problème avec les clients anciens qui nécessitent de tels en-têtes (Ceci affecte tous les modules qui utilisent ces variables d'environnement).
mod_authz_core Conteneurs de logique d'autorisation
La directive Require et les directives de conteneurs associées, comme <RequireAll>, permettent de définir une logique d'autorisation avancée.
mod_rewrite
La directive RewriteRule dispose maintenant des drapeaux [QSD] (Query String Discard) et [END] qui permettent de simplifier les scénarios de réécriture courants.
Possibilité d'utiliser des expressions booléennes complexes dans la directive RewriteCond.
Possibilité d'utiliser des requêtes SQL en tant que fonctions dans la directive RewriteMap.
mod_ldap, mod_authnz_ldap
mod_authnz_ldap ajoute le support des groupes imbriqués.
mod_ldap apporte les directives LDAPConnectionPoolTTL et LDAPTimeout, ainsi que d'autres améliorations dans le traitement des délais. Ceci s'avère utile pour les configurations où un pare-feu à mémoire d'état (stateful) rejète les connexions inactives vers le serveur LDAP.
mod_ldap propose la directive LDAPLibraryDebug qui permet de journaliser les informations de débogage fournies par la boîte à outils LDAP utilisée.
mod_info
mod_info est maintenant capable d'afficher la configuration préinterprétée sur stdout au cours du démarrage du serveur.
mod_auth_basic
Nouveau mécanisme générique permettant d'effectuer une authentification basique (disponible à partir de la version 2.4.5).

Améliorations des programmes

fcgistarter
Nouvel utilitaire pour le démarrage des démons FastCGI.
htcacheclean
Les URLs présentes dans le cache peuvent maintenant être affichées, accompagnées éventuellement de leurs métadonnées.
Possibilité de supprimer explicitement des URLs individuelles présentes dans le cache.
Les tailles de fichiers peuvent maintenant être arrondies au multiple de la taille de bloc donnée, les limites de taille collant de ce fait d'avantage à la taille réelle sur disque.
La taille du cache peut maintenant être limitée par le nombre d'inodes, en plus de la possibilité de limitation par la taille des fichiers.
rotatelogs
Possibilité de créer un lien vers le fichier journal courant.
Possibilité d'invoquer un script personnalisé après la rotation.
htpasswd, htdbm
Support de l'algorithme bcrypt (disponible à partir de la version 2.4.4).

Documentation

mod_rewrite
La documentation du module mod_rewrite a été réorganisée et presque entièrement réécrite en mettant l'accent sur les exemples et l'utilisation courante, ainsi que sur l'incitation à utiliser d'autres solutions lorsque cela s'avère plus approprié. Le document Rewrite Guide constitue maintenant une section de premier niveau ; il est mieux organisé et contient beaucoup plus de détails.
mod_ssl
La documentation du module mod_ssl a été grandement améliorée, avec plus d'exemples et un niveau "Bien démarrer" qui s'ajoutent aux détails techniques déjà présents dans la précédente documentation.
Caching Guide
Le Guide de la mise en cache a été réécrit afin de bien faire la différence entre les fonctionnalités de mise en cache de la RFC2616 HTTP/1.1 fournies par le module mod_cache, et la mise en cache générique de type clé/valeur fournie par l'interface socache, mais aussi pour couvrir la mise en cache spécialisée fournie par des mécanismes tels que ceux du module mod_file_cache.

Modifications concernant les développeur de modules

Ajout de code pour la vérification de la configuration
Une nouvelle fonction, check_config, a été ajoutée et s'exécute entre les fonctions pre_config et open_logs. Elle s'exécute aussi avant la fonction test_config si l'option -t est passée au démon httpd. La fonction check_config permet aux modules de vérifier l'interdépendance des valeurs des directives de configuration et d'ajuster ces valeurs, alors que les messages du serveur peuvent encore être affichés sur la console. L'utilisateur est ainsi averti des erreurs de configuration avant que la fonction du noyau open_logs ne redirige les sorties de la console vers le journal des erreurs.
Ajout d'un analyseur syntaxique d'expressions
Nous disposons à présent d'un analyseur générique d'expressions, dont l'API est décrite dans ap_expr.h. Il s'agit d'une adaptation de l'analyseur qu'on trouvait auparavant dans mod_ssl.
Conteneurs de logique d'autorisation
Afin de fournir une logique d'autorisation avancée via des directives telles que <RequireAll>, les modules d'autorisation s'enregistrent maintenant en tant que fournisseur par le biais de ap_register_auth_provider().
Interface de mise en cache des petits objets
Le fichier d'en-têtes ap_socache.h fournit une interface à base de fournisseur pour la mise en cache des petits objets de données, en s'inspirant de l'implémentation précédente du cache de session par mod_ssl. Sont supportés actuellement : les fournisseurs utilisant un tampon cyclique en mémoire partagée, les fichiers dbm sur disque, et les caches distribués de type memcache.
Ajout du point d'ancrage Cache Status
Le module mod_cache inclut maintenant un nouveau point d'ancrage, cache_status, qui est appelé lorsque la décision à propos de la mise en cache est connue. Il en existe une implémentation par défaut qui ajoute les en-têtes optionnels X-Cache et X-Cache-Detail à la réponse.

La documentation du développeur contient une liste détaillée des modifications de l'API.


Aperçu des nouvelles fonctionnalités de la version 2.2 du serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Aperçu des nouvelles fonctionnalités de la version 2.2 du serveur HTTP Apache

Ce document décrit quelques uns des changements principaux entre les versions 2.0 et 2.2 du serveur HTTP Apache. Pour les nouvelles fonctionnalités ajoutées depuis la version 1.3, se référer au document 2.0 new features.

Améliorations du système de base

Authn/Authz
Les modules d'authentification et d'autorisation intégrés ont été refondus. Le nouveau module mod_authn_alias (supprimé dans la version 2.3/2.4) permet de simplifier considérablement certaines configurations d'authentification. Voir modification des noms de modules, et les changements pour le développeur pour plus d'informations sur les conséquences de ces changements pour les utilisateurs et les développeurs de modules.
Mise en cache
mod_cache, mod_cache_disk, et mod_mem_cache (supprimés dans la version 2.3/2.4) ont subi de nombreuses modifications, et l'on considère qu'ils ont maintenant atteint un degré de qualité suffisant pour leur mise en production. Le programme htcacheclean a été ajouté afin de rendre plus propre la configuration du module mod_cache_disk.
Configuration
L'agencement de la configuration par défaut a été simplifié et modularisé. Les portions de configuration qui peuvent être utilisées pour activer des fonctionnalités courantes sont maintenant intégrées à Apache, et peuvent être facilement ajoutées à la configuration principale du serveur.
Arrêt en douceur
Les modules MPM prefork, worker et event permettent maintenant l'arrêt en douceur de httpd au moyen du signal graceful-stop. La directive GracefulShutdownTimeout a été ajoutée dans le but de spécifier un délai optionnel, après lequel httpd s'arrêtera quel que soit le statut des requêtes en cours.
Mise en oeuvre du proxy
Le nouveau module mod_proxy_balancer fournit des services de répartition de charge (load balancing) pour le module mod_proxy. Le nouveau module mod_proxy_ajp ajoute le support pour le Protocole JServ de Apache version 1.3 qu'utilise Apache Tomcat.
Mise à jour de la bibliothèque des expressions rationnelles
La version 5.0 de la Perl Compatible Regular Expression Library (PCRE) est maintenant disponible. httpd peut être configuré pour utiliser une PCRE choisie en passant l'option --with-pcre au script configure.
Filtrage intelligent
Le module mod_filter permet la configuration dynamique de la chaîne de filtrage en sortie. Il permet d'insérer des filtres conditionnels basés sur toute requête, en-tête de réponse ou variable d'environnement, et fait table rase des problèmes de dépendances et d'ordonnancement rencontrés avec l'architecture 2.0.
Support des gros fichiers
httpd supporte maintenant les fichiers d'une taille supérieure à 2GB sur les systèmes 32 bits UNIX modernes. Le support des corps de requête d'une taille supérieure à 2GB a aussi été ajouté.
Module MPM Event
Le module MPM event utilise un thread séparé pour gérer les requêtes "Keep alive" et accepter des connexions. Les requêtes "Keep alive" requéraient traditionnellement un processus httpd dédié pour leur gestion. Ce processus dédié ne pouvait plus être réutilisé jusqu'à ce que le délai "Keep Alive" soit écoulé.
Support des bases de données SQL
Le module mod_dbd, associé à l'environnement apr_dbd, fournit le support SQL direct aux modules qui en ont besoin. Supporte la mise en commun des connexions dans les modules MPM threadés.

Améliorations des modules

Authn/Authz
Les modules du répertoire aaa ont été renommés et fournissent un support amélioré pour la méthode d'authentification digest. Par exemple, mod_auth est maintenant scindé en deux modules : mod_auth_basic et mod_authn_file; mod_auth_dbm s'appelle maintenant mod_authn_dbm; mod_access a été renommé en mod_authz_host. Est également apparu le nouveau module mod_authn_alias (supprimé dans la version 2.3/2.4) qui simplifie certaines configurations d'authentification.
mod_authnz_ldap
Ce module est un portage de la version 2.0 du module mod_auth_ldap vers la version 2.2 du framework Authn/Authz. Les nouvelles fonctionnalités comprennent l'utilisation des valeurs d'attributs LDAP et des filtres de recherche avancés dans la directive Require.
mod_authz_owner
Un nouveau module qui autorise l'accès à un fichier en fonction de son propriétaire dans le système de fichiers
mod_version
Un nouveau module qui permet d'activer des blocs de configuration en fonction de la version du serveur en cours d'exécution.
mod_info
Un nouvel argument ?config a été ajouté, qui permettra d'afficher les directives de configuration telles qu'elles sont interprétées par Apache, y compris le nom de fichier et le numéro de ligne. Le module montre aussi l'ordre des points d'entrée de traitement d'une requête (request hooks) ainsi que des informations de construction supplémentaires, d'une manière similaire à httpd -V.
mod_ssl
Le support de la RFC 2817 a été ajouté, ce qui permet de passer d'une connexion en clair au chiffrement TLS.
mod_imagemap
mod_imap a été renommé en mod_imagemap afin d'éviter une confusion pour les utilisateurs.

Améliorations des programmes

httpd
Une nouvelle option de ligne de commande -M a été ajoutée, qui fournit la liste de tous les modules chargés en fonction de la configuration réelle. À la différence de l'option -l, cette liste inclut les Objets Dynamiques Partagés (DSOs) chargés par l'intermédiaire du module mod_so.
httxt2dbm
Un nouveau programme servant à générer des fichiers dbm à partir d'une source au format texte, à utiliser avec la directive RewriteMap et le type de mise en correspondance dbm.

Changements pour le développeur de module

APR 1.0 API
Apache 2.2 utilise l'API APR 1.0. Toutes les fonctions et symboles obsolètes ont été supprimés du code de APR et APR-Util. Pour plus de détails, consultez le site web d'APR.
Authn/Authz
Les modules d'authentification et d'autorisation intégrés ont été renommés de la manière suivante:
  • mod_auth_* -> Modules qui implémentent un mécanisme d'authentification HTTP
  • mod_authn_* -> Modules qui fournissent un dispositif d'authentification en arrière-plan
  • mod_authz_* -> Modules qui implémentent l'autorisation (ou l'accès)
  • mod_authnz_* -> Modules qui implémentent à la fois l'authentification & l'autorisation
L'organisation des méthodes d'authentification a également été revue, ce qui va simplifier grandement l'ajout de nouvelles méthodes d'authentification.
Journalisation des erreurs de connexion
Une nouvelle fonction a été ajoutée, ap_log_cerror, afin de pouvoir enregistrer les erreurs qui surviennent au cours de la connexion du client. Une fois enregistré, le message inclut l'adresse IP du client.
Ajout d'une portion de code pour la vérification de la configuration
Un nouvel élément de traitement a été ajouté, test_config, afin d'aider les modules qui ne veulent exécuter un code spécial que si l'utilisateur passe le paramètre -t à httpd.
Définition de la taille de la pile pour les modules MPM en processus légers
Une nouvelle directive a été ajoutée, ThreadStackSize afin de définir la taille de la pile pour tous les modules MPM en processus légers (modules threadés). Ceci s'avère nécessaire pour certains modules tiers sur des plateformes dont la taille de la pile des threads par défaut est trop petite.
Gestion de protocole pour les filtres en sortie
Par le passé, chaque filtre devait s'assurer que les en-têtes de réponse corrects étaient générés dans la mesure où il les affectait. Les filtres peuvent maintenant déléguer la gestion courante du protocole au module mod_filter, à l'aide des appels ap_register_output_filter_protocol ou ap_filter_protocol.
Ajout d'un élément de traitement pour le processus père (monitor hook)
Ce nouvel élément de traitement permet aux modules de lancer des jobs réguliers/planifiés au niveau du processus père (root).
Modifications de l'API de traitement des expressions rationnelles
Le fichier d'en-tête pcreposix.h n'est plus disponible ; il a été remplacé par le nouveau fichier d'en-tête ap_regex.h. L'implémentation POSIX.2 regex.h exposée dans l'ancien fichier d'en-tête est maintenant disponible dans l'espace de nommage ap_ depuis ap_regex.h. Les appels à regcomp, regexec, etc... peuvent être remplacés par des appels à ap_regcomp, ap_regexec.
Cadre d'application DBD (API pour base de données SQL)

Avec Apache 1.x et 2.0, les modules nécessitant un processus SQL d'arrière-plan devaient s'en charger eux-mêmes. En dehors du fait de réinventer la roue, ceci peut s'avérer très inefficace, par exemple lorsque plusieurs modules maintiennent chacun leurs propres connexions.

Apache 2.1 et supérieur fournissent l'API ap_dbd qui permet la gestion des connexions à la base de données (y compris les stratégies optimisées pour les modules MPM threadés et non threadés), tandis que APR 1.2 et supérieur fournissent l'API apr_dbd qui permet l'interaction avec la base de données.

Les nouveaux modules DEVRAIENT désormais utiliser ces APIs pour toutes les opérations liées aux bases de données SQL. De même, les applications existantes DEVRAIENT être mises à jour lorsque c'est possible, que ce soit de manière transparente ou sous forme d'une option recommandée à leurs utilisateurs.


Vue d'ensemble des nouvelles fonctionnalités de la version 2.0 du serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Vue d'ensemble des nouvelles fonctionnalités de la version 2.0 du serveur HTTP Apache

Ce document décrit les changements majeurs apportés entre les versions 1.3 et 2.0 du serveur HTTP Apache.

Voir aussi

  • Migrer à 2.0 depuis la version 1.3

Améliorations du Système de Base

Threading Unix
Sur les systèmes Unix qui supportent les threads POSIX, Apache httpd peut à présent tourner en mode hybride multi-processus et multi-threadé, ce qui augmente l'extensibilité et la performance du serveur pour la plupart des configurations.
Nouveau Système de Compilation
Le processus de compilation a été refait de A à Z; il utilise à présent autoconf et libtool, ce qui rend la compilation d'Apache httpd plus familière aux utilisateurs d'autre logiciels de mème type.
Support Multiprotocole
Le serveur HTTP Apache dispose désormais de l'infrastructure nécessaire pour supporter d'autres protocoles. Le module mod_echo illustre ces possibilités.
Support amélioré des Plate-formes non-Unix
Le serveur HTTP Apache 2.0 se montre plus rapide et plus stable sur les plate-formes non Unix, telles BeOS, OS/2, NetWare et Windows. L'apparition des Modules Multi-Processus (MPMs), ainsi que de la bibliothèque "Apache Portable Runtime" (APR) permet à Apache de tirer parti des API natives de ces plate-formes, sans s'appuyer sur leurs couches POSIX souvent boguées et peu optimisées.
Nouvelle API d'Apache httpd
L'Interface de Programmation (API) des modules a beaucoup changé avec le passage à la version 2.0. Les problèmes d'ordre et de priorité des modules, rencontrés avec la version 1.3, devraient maintenant être résolus. Apache 2.0 gère ces problèmes de façon automatique. L'ordre des modules est géré au moyen de "crochets" (hooks), ce qui rend la gestion flexible. De nouveaux appels ont été également créés afin de permettre l'implémentation d'autres fonctions dans les modules, sans devoir corriger le noyau du serveur HTTP Apache.
Support IPv6
Sur les systèmes où la bibliothèque Apache Portable Runtime supporte IPv6, Apache peut par défaut écouter sur des interfaces de connexions IPv6. Les directives Listen, NameVirtualHost et VirtualHost supportent également les adresses IPv6 (comme par exemple, dans "Listen[2001:db8::1]:8080").
Filtering
Il est maintenant possible d'écrire des modules pour Apache httpd pour filtrer les flux de données entrant ou sortant du serveur. A titre d'exemple, il est possible de filtrer des directives Server Side Include de la sortie standard d'un script CGI, au moyen du filtre INCLUDES fourni par le module mod_include. Le module mod_ext_filter permet quant à lui l'utilisation comme filtres de programmes externes à Apache, de la même manière qu'on peut utiliser des programmes CGI comme Handlers.
Réponses d'Erreurs Multilangues
Les messages d'erreur envoyés au navigateur existent à présent en plusieurs langues avec des documents SSI. Ces messages peuvent être personnalisés par l'administrateur afin de s'intégrer avec le site web.
Simplification de la Configuration
Beaucoup de directives, auparavant peu claires, ont été simplifiées. Les directives Port et BindAddress, souvent sources d'incompréhension, ont disparus. Désormais seule la directive Listen sert de liaison pour les adresses IP; la directive ServerName ne précise le nom du serveur et son port que pour les redirections et la gestion des hôtes virtuels.
Support natif de l'Unicode sous Windows NT
Apache httpd 2.0 sur Windows NT utilise à présent l'utf-8 pour tous les noms de fichiers. Ces noms de fichiers sont directement traduits vers l'encodage Unicode du système de fichiers, ce qui permet le support multilangue pour toutes les installations sur la famille NT de Windows, y compris Windows 2000 et Windows XP.Ce support n'est pas fonctionnel pour Windows 95, 98 ni ME, qui utilisent les pages de code locales pour les accès au système de fichiers, comme auparavant.
Mise à jour de la Bibliothèque d'Expressions Rationnelles
Apache httpd 2.0 contient la bibliothèque d'expressions rationnelles compatible Perl (Perl Compatible Regular Expression Library - PCRE). Toutes les expressions rationnelles sont dont gérées avec la syntaxe de Perl 5, plus puissante.

Amélioration des Modules

mod_ssl
Apparu dans Apache httpd 2.0, ce module est une interface aux protocoles de chiffrement SSL/TLS fournis par OpenSSL.
mod_dav
Apparu dans Apache httpd 2.0, ce module implémente les spécifications HTTP de gestion distribuée de versions et de rédaction (Distributed Authoring and Versioning - DAV), destinées à la mise en ligne et à la maintenance des contenus Web.
mod_deflate
Module apparu dans Apache httpd 2.0, mod_deflate permet aux navigateurs qui le supportent de demander la compression des contenus envoyés par le serveur. Cela a l'avantage de réduite l'occupation de la bande passante.
mod_auth_ldap
Apparu dans Apache httpd 2.0.41, ce module permet aux administrateurs d'utiliser un arbre LDAP pour gérer la base d'utilisateurs pour les Authentifications Basiques HTTP. Un module voisin, mod_ldap, permet de globaliser les connexions à l'arbre LDAP et de garder en mémoire cache ces accès.
mod_auth_digest
Améliore les fonctions de cache sur une session entre les différents processus, en utilisant de la mémoire partagée.
mod_charset_lite
Apparu dans Apache httpd 2.0, ce module expérimental permet la conversion et l'enregistrement entre jeux de caractères.
mod_file_cache
Apparu dans Apache httpd 2.0, ce module implémente les fonctionnalités du module mod_mmap_static présent du serveur HTTP Apache 1.3, et offre des fonctions plus avancées pour la gestion du cache.
mod_headers
Ce module gagne beaucoup de flexibilité avec Apache httpd 2.0 : on peut désormais l'utiliser pour modifier les en-têtes des requêtes utilisés par mod_proxy, et pour positionner les en-têtes des réponses de manière conditionnelle.
mod_proxy
Le module proxy a été réécrit de A à Z. Il tire maintenant avantage de la nouvelle infrastructure de filtrage, et implémente un mandataire plus fiable, et conforme aux normes HTTP/1.1. De nouvelles sections de configuration ajoutées à <Proxy> donnent un contrôle plus lisible et un traitement plus rapide des requêtes mandatées ; les configurations surchargées <Directory "proxy:..."> ne sont pas supportées. Le module a aussi été fragmenté en plusieurs modules qui gèrent chacun leur protocole : proxy_connect, proxy_ftp et proxy_http.
mod_negotiation
Une nouvelle directive, ForceLanguagePriority a été ajoutée, elle permet de garantir que le client reçoit un seul document dans tous les cas, au lieu de réponses NOT ACCEPTABLE ou MULTIPLE CHOICES. Les algorithmes gérant la négociation et les vues multiples (MultiViews) ont été nettoyés et donnent des réponses plus logiques. Un nouveau format de carte de types (map type) qui peut gérer le contenu de documents a aussi été ajouté.
mod_autoindex
Les listes auto-générées par Autoindex sont à présent configurables, et peuvent utiliser des tables HTML pour une mise en forme plus propre. L'ordre d'affichage des fichiers est également finement paramètrable, comme pour le tri par version, et le filtrage par caractères jokers du listage du répertoire.
mod_include
De nouvelles directives permettent de modifier la valeur par défaut des drapeaux start et end des éléments SSI. Ces directives permettent à la configuration d'affichage de dates et heures d'être effectuée dans le fichier de configuration principal, plutôt que dans le document SSI. Les réponses données par des recherches par expressions rationnelles (qui gèrent à présent les regex Perl) sont recupérées au moyen des variables $0 à $9.
mod_auth_dbm
Plusieurs bases de données DBM sont supportées, et sélectionnables via la directive AuthDBMType.


The Apache License, Version 2.0 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

The Apache License, Version 2.0

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions

    "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

    "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

    "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

    "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

    "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

    "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

    "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

    "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

    "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

    "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

  2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
  3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
  4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
    1. You must give any other recipients of the Work or Derivative Works a copy of this License; and
    2. You must cause any modified files to carry prominent notices stating that You changed the files; and
    3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
    4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

    You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

  5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
  6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
  7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
  8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
  9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.

Copyright [yyyy] [name of copyright owner]

Licensed 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.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Compilation et installation - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Compilation et installation

Ce document couvre l'installation et la compilation du serveur HTTP Apache sur les systèmes Unix et similaires seulement. Pour la compilation et l'installation sous Windows, voir Utiliser le serveur HTTP Apache avec Microsoft Windows et Compilation d'Apache sous Microsoft Windows. Pour les autres plateformes, se référer à la documentation par plateforme.

Apache httpd utilise libtool et autoconf afin de créer un environnement de construction similaire à la plupart des projets Open Source .

Si vous effectuez une mise à jour depuis une version mineure vers la suivante (par exemple, 2.4.9 à 2.4.10), veuillez passer à la section mise à jour.

Voir aussi

  • Configuration de l'arborescence des sources
  • Démarrer Apache httpd
  • Arrêt et redémarrage

Aperçu pour les plus pressés

Installation sous Fedora/CentOS/Red Hat Enterprise Linux
sudo yum install httpd
sudo service httpd start
Les dernières versions de ces distributions préfèrent dnf à yum. Voir la documentation du projet Fedora pour des informations spécifiques à cette plateforme.
Installation sous Ubuntu/Debian
sudo apt install apache2
sudo service apache2 start
Voir la documentation Ubuntu pour des informations spécifiques à cette plateforme.
Installation à partir des sources
Téléchargement | Téléchargez la dernière version depuis http://httpd.apache.org/download.cgi
Extraction $ gzip -d httpd-NN.tar.gz
$ tar xvf httpd-NN.tar
$ cd httpd-NN
Configuration | $ ./configure --prefix=PREFIX
Compilation | $ make
Installation | $ make install
Personnalisation | $ vi PREFIX/conf/httpd.conf
Test | $ PREFIX/bin/apachectl -k start

NN doit être remplacé par le numéro de version courant, et PREFIX par le chemin du répertoire d'installation. Si PREFIX n'est pas spécifié, le chemin du répertoire d'installation prendra sa valeur par défaut, à savoir /usr/local/apache2.

Chaque étape du processus de compilation et d'installation est décrite plus en détails ci-dessous, à commencer par les prérequis pour compiler et installer Apache httpd.

L'installation sous votre plateforme favorite n'est pas traitée ici ? N'hésitez pas à nous aider à compléter cette documentation en nous faisant profiter de votre expérience.

Prérequis

Les prérequis pour la construction d'Apache httpd sont les suivants:

APR et APR-Util
APR et APR-Util doivent être déjà installés sur votre système. Si ce n'est pas le cas, ou si vous préférez ne pas utiliser les versions fournies par le système, téléchargez les dernières versions d'APR et APR-Util depuis Apache APR, décompressez-les respectivement dans /racine_sources_httpd/srclib/apr et /racine_sources_httpd/srclib/apr-util (les noms des répertoires ne doivent pas comporter de numéros de versions ; par exemple, la distribution d'APR doit se trouver dans /racine_sources_httpd/srclib/apr/), et utilisez l'option --with-included-apr du script ./configure. Sur certaines plateformes, vous devrez peut-être installer les paquets -dev correspondants pour permettre la compilation de httpd avec les versions installées d'APR et APR-Util.
Bibliothèque d'expressions rationnelles compatibles Perl (PCRE)
Cette bibliothèque est nécessaire mais n'est plus fournie avec la distribution de httpd. Téléchargez le code source depuis http://www.pcre.org ou installez un portage du paquet. Si votre suite de compilation ne trouve pas le script pcre-config installé au cours du processus de construction de PCRE, indiquez son chemin via l'option --with-pcre du script ./configure. Sur certaines plateformes, vous devrez peut-être installer les paquets -dev correspondants pour permettre la compilation de httpd avec la version installée de PCRE.
Espace disque
Assurez-vous d'avoir au moins 50 Mo d'espace disque disponible temporaire. Après l'installation le serveur occupe approximativement 10 Mo d'espace disque. L'espace disque réellement nécessaire va varier considérablement en fonction de vos options de configuration, de la présence éventuelle de modules tiers, et bien entendu de la taille de votre site web et des sites que vous hébergez sur votre serveur.
Compilateur ANSI-C et système de construction
Vous devez disposer d'un compilateur ANSI-C. Le compilateur GNU C (GCC) de la Free Software Foundation (FSF) est recommandé. Si vous ne possédez pas GCC, assurez-vous au moins que votre compilateur soit compatible ANSI. En outre, votre PATH doit contenir les outils de construction de base tels que make.
Connaissance de l'heure exacte
Les éléments du protocole HTTP font référence à l'heure du jour. Par conséquent, il est nécessaire d'équiper votre système d'un dispositif de synchronisation du temps. Les programmes ntpdate ou xntpd, basés sur le protocole NTP, sont couramment utilisés à cet effet. Voir la page d'accueil de NTP pour plus de détails à propos du logiciel NTP et des serveurs de temps publics.
Perl 5 [OPTIONNEL]
L'interpréteur Perl 5 (les versions 5.003 ou supérieures conviennent) est nécessaire pour l'exécution de certains scripts comme apxs ou dbmmanage (qui sont écrits en Perl). Si le script configure ne trouve pas d'interpréteur Perl 5, vous ne pourrez pas utiliser les scripts qui en ont besoin. Bien entendu, vous pourrez tout de même construire et utiliser Apache httpd.

Téléchargement

Le serveur HTTP Apache peut être téléchargé à partir du site de téléchargement du serveur HTTP Apache, qui fournit la liste de nombreux miroirs. Il sera plus commode à la plupart des utilisateurs d'Apache sur les systèmes UNIX ou similaires de télécharger et de compiler la version sources. Le processus de construction (décrit ci-dessous) est simple, et vous permet de personnaliser votre serveur selon vos besoins. En outre, les versions binaires sont souvent plus anciennes que les dernières versions sources. Si vous téléchargez une version binaire, suivez les instructions décrites dans le fichier INSTALL.bindist inclus dans la distribution.

Après le téléchargement, il est important de vérifier que vous disposez d'une version complète et non modifiée du serveur HTTP Apache. Vous pouvez le faire en testant l'archive téléchargée à l'aide de la signature PGP. Vous trouverez les détails de cette opération sur la page de téléchargement ainsi qu'un exemple précis décrivant l'utilisation de PGP.

Extraction

L'extraction des sources depuis l'archive du serveur HTTP Apache consiste simplement à décompresser et à désarchiver cette dernière :

$ gzip -d httpd-NN.tar.gz
$ tar xvf httpd-NN.tar

Ceci créera, dans le répertoire courant, un nouveau répertoire contenant le code source de la distribution. Vous devrez vous positionner dans ce répertoire avant de procéder à la compilation du serveur.

Configuration de l'arborescence des sources

L'étape suivante consiste à configurer l'arborescence des sources d'Apache en fonction de votre plateforme et de vos besoins personnels. Le script configure, situé à la racine du répertoire de la distribution, a été conçu à cet effet (Les développeurs qui téléchargent une version non officielle de l'arborescence des sources d'Apache devront disposer de autoconf et libtool et exécuter buildconf avant de passer à l'étape suivante, ce qui n'est pas nécessaire pour les versions officielles).

Pour configurer l'arborescence des sources avec les valeurs par défaut pour toutes les options, entrez simplement ./configure. Pour modifier les valeurs des options, configure accepte toute une variété de variables et d'options de ligne de commande.

L'option la plus importante --prefix est le chemin du répertoire d'installation d'Apache, car Apache doit être configuré en fonction de ce chemin pour pouvoir fonctionner correctement. Il est possible de définir plus finement le chemin d'installation des fichiers à l'aide d'options supplémentaires de configure.

À ce niveau, vous pouvez aussi spécifier de quelles fonctionnalités vous voulez disposer dans Apache en activant ou désactivant des modules. Apache est fourni avec un grand nombre de modules inclus par défaut. Ils seront compilés en tant qu'objets partagés (DSOs) qui pourront être chargés ou déchargés à l'exécution. Vous pouvez aussi choisir de compiler les modules statiquement via l'option --enable-module=static.

Des modules supplémentaires peuvent être activés à l'aide de l'option --enable-module, où module est le nom du module sans la chaîne mod_ et où tout caractère de soulignement est converti en tiret. D'une manière similaire, vous pouvez désactiver des modules à l'aide de l'option --disable-module. Faites très attention en utilisant ces options, car configure n'est pas en mesure de vous avertir si le module que vous avez spécifié n'existe pas; il ignorera tout simplement l'option.

En outre, vous devrez peut-être fournir au script configure des informations supplémentaires sur le chemin de votre compilateur, de vos bibliothèques, ou de vos fichiers d'en-têtes. A cet effet, vous pouvez passer des options de ligne de commande ou des variables d'environnement au script configure. Pour plus d'informations, voir la page de manuel de configure, ou lancez le script configure avec l'option --help.

Pour vous faire une idée des possibilités qui s'offrent à vous, voici un exemple typique de compilation d'Apache avec le répertoire d'installation /sw/pkg/apache, un compilateur et des drapeaux particuliers et les deux modules additionnels mod_ldap et mod_lua :

$ CC="pgcc" CFLAGS="-O2" \
./configure --prefix=/sw/pkg/apache \
--enable-ldap=shared \
--enable-lua=shared

Plusieurs minutes peuvent être nécessaires à configure pour tester la disponibilité des fonctionnalités au sein de votre système, et construire les Makefiles qui seront utilisés par la suite pour compiler le serveur.

Vous trouverez une description détaillée des options de configure dans sa page de manuel.

Construction

Vous pouvez maintenant construire les différents éléments qui composent le paquet Apache en lançant tout simplement la commande :

$ make

Vous devez être patient, car il faut plusieurs minutes pour compiler une configuration de base, et cette durée peut varier considérablement en fonction de votre matériel et du nombre de modules que vous avez activés.

Installation

Il est temps maintenant d'installer le paquet dans le répertoire d'installation défini par PREFIX (voir plus haut l'option --prefix) en lançant:

$ make install

Cette étape nécessite habituellement les privilèges de root, car PREFIX est en général un répertoire possèdant des droits en écriture restreints.

Si vous effectuez une mise à jour, l'installation n'écrasera pas vos fichiers de configuration ou autres documents.

Personnalisation

Ensuite, vous pourrez personnaliser votre Serveur HTTP Apache en éditant les fichiers de configuration situés dans PREFIX/conf/.

$ vi PREFIX/conf/httpd.conf

Consultez le manuel d'Apache situé dans PREFIX/docs/manual/ ou http://httpd.apache.org/docs/2.4/ pour la version la plus récente de ce manuel et la liste complète des directives de configuration disponibles.

Test

Vous pouvez maintenant démarrer votre serveur HTTP Apache en lançant:

$ PREFIX/bin/apachectl -k start

Vous devriez alors pouvoir requérir votre premier document à l'aide de l'URL http://localhost/. La page web que vous voyez est située dans le répertoire défini par la directive DocumentRoot, qui est généralement PREFIX/htdocs/. Pour arrêter le serveur, lancez:

$ PREFIX/bin/apachectl -k stop

Mise à jour

La première étape d'une mise à jour consiste à lire l'annonce de la sortie de la nouvelle version et le fichier CHANGES dans la distribution des sources afin de déceler toutes les modifications qui pourraient affecter votre site. Lors d'un changement majeur de version (par exemple de 2.0 à 2.2 ou de 2.2 à 2.4), il y aura certainement des différences importantes quant à la configuration de la compilation et de l'exécution qui nécessiteront des ajustements manuels. Tous les modules devront aussi être mis à jour pour qu'ils s'adaptent aux changements de l'API des modules.

La mise à jour d'une version mineure à la suivante (par exemple, de 2.2.55 à 2.2.57) est plus aisée. Le processus make install n'écrasera aucun de vos documents existants, fichiers de log, ou fichiers de configuration. De plus, les développeurs font tout leur possible pour éviter les changements entraînant une incompatibilité dans les options de configure, la configuration de l'exécution, ou l'API des modules d'une version mineure à l'autre. Dans la plupart des cas, vous pourrez utiliser une ligne de commande configure identique, le même fichier de configuration, et tous vos modules continueront de fonctionner.

Pour effectuer une mise à jour entre deux versions mineures, commencez par trouver le fichier config.nice dans le répertoire de construction de votre serveur installé ou à la racine de l'arborescence des sources de votre ancienne installation. Il contient la reproduction exacte de la ligne de commande configure que vous avez utilisée pour configurer l'arborescence des sources. Ensuite, pour mettre à jour l'ancienne version vers la nouvelle, il vous suffit de copier le fichier config.nice dans l'arborescence des sources de la nouvelle version, de l'éditer pour effectuer toute modification souhaitée, et de lancer :

$ ./config.nice
$ make
$ make install
$ PREFIX/bin/apachectl -k graceful-stop
$ PREFIX/bin/apachectl -k start

Vous devez toujours effectuer un test de la nouvelle version dans votre environnement avant de la mettre en production. Par exemple, vous pouvez installer et exécuter la nouvelle version en parallèle avec l'ancienne en utilisant une option --prefix et un port différents (en ajustant la directive Listen) afin de déceler toute incompatibilité avant d'effectuer la mise à jour définitive.

Vous pouvez ajouter des arguments supplémentaires à config.nice ; ils seront alors ajoutés aux options de votre script configure original :

$ ./config.nice --prefix=/home/test/apache --with-port=90

Paquets tiers

De nombreux tiers fournissent leur propre distribution du serveur HTTP Apache à installer sur une plate-forme particulière. On peut citer les différentes distributions Linux, divers paquets tiers Windows, Mac OS X, Solaris et de nombreux autres.

Notre license logicielle non seulement permet, mais aussi encourage ce genre de redistribution. Cependant, ceci conduit à une situation ou l'organisation de la configuration et les valeurs par défaut de votre installation du serveur peuvent ne pas correspondre à ce qui est écrit dans la documentation. Bien que fâcheuse, cette situation n'est pas appelée à évoluer de sitôt.

Une description de ces distributions tierces est maintenue dans le wiki du serveur HTTP, et doit en refléter l'état actuel. Vous devrez cependant vous familiariser par vous-même avec la gestion du paquet de votre plate-forme particulière et les procédures d'installation.


Démarrage d'Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Démarrage d'Apache

Sous Windows, Apache est habituellement lancé en tant que service. Pour plus de détails, voir Démarrer Apache en tant que service.

Sous Unix, le programme httpd est lancé en mode démon et s'exécute de manière permanente en arrière-plan pour gérer les requêtes. Ce document décrit comment invoquer httpd.

Voir aussi

  • Arrêt et redémarrage
  • httpd
  • apachectl

Comment Apache démarre

Si la directive Listen spécifiée dans le fichier de configuration est à sa valeur par défaut de 80 (ou tout autre port inférieur à 1024), il est nécessaire de posséder les privilèges root pour pouvoir démarrer apache, et lui permettre d'être associé à ce port privilégié. Lorsque le serveur est démarré, il effectue quelques opérations préliminaires comme ouvrir ses fichiers de log, puis il lance plusieurs processus enfants qui ont pour rôle d'écouter et de répondre aux requêtes des clients. Le processus httpd principal continue à s'exécuter sous l'utilisateur root, tandis que les processus enfants s'exécutent sous un utilisateur aux privilèges restreints. Ceci s'effectue par la voie du Module Multi-Processus (MPM).

Il est recommandé d'utiliser le script de contrôle apachectl pour invoquer l'exécutable httpd. A cet effet, ce script définit certaines variables d'environnement nécessaires pour permettre à httpd de fonctionner correctement sous certains systèmes d'exploitation. apachectl accepte des arguments de ligne de commande ; ainsi toute option de httpd peut aussi être utilisée avec apachectl. Vous pouvez aussi éditer directement le script apachectl en modifiant la variable HTTPD située en début de script pour spécifier la localisation du binaire httpd et tout argument de ligne de commande que vous souhaitez voir systématiquement présent.

La première chose qu'effectue httpd quand il est invoqué est de localiser et lire le fichier de configuration httpd.conf. La localisation de ce fichier est définie à la compilation, mais il est possible d'en spécifier une autre à l'exécution en utilisant l'option de ligne de commande -f comme suit:

/usr/local/apache2/bin/apachectl -f /usr/local/apache2/conf/httpd.conf

Si tout se passe bien pendant le démarrage, le serveur va se dissocier du terminal et l'invite de commande réapparaîtra presque immédiatement. Ceci indique que le serveur a démarré et est en cours d'exécution. À partir de ce moment, vous pouvez utiliser votre navigateur pour vous connecter au serveur et afficher la page de test située dans le répertoire défini par la directive DocumentRoot

Erreurs en cours de démarrage

Si un problème fatal survient pendant le démarrage d'Apache, ce dernier va afficher un message décrivant le problème sur la console ou enregistrer ces informations dans le fichier défini par la directive ErrorLog avant de quitter. Un des messages d'erreur les plus courants est "Unable to bind to Port ...". Ce message d'erreur est habituellement provoqué par :

  • Une tentative de démarrage du serveur avec un port privilégié sans être connecté root
  • Une tentative de démarrage du serveur alors qu'une autre instance d'Apache ou un autre serveur web est déjà associé au même port.

Pour plus d'instructions de dépannage, consultez la FAQ Apache.

Lancement au démarrage du système

Si vous souhaitez que votre serveur web soit automatiquement disponible après un redémarrage du système, vous devez ajouter un appel à apachectl à vos fichiers de démarrage système (en général rc.local ou un fichier dans un répertoire rc.N), ce qui démarrera Apache sous l'utilisateur root. Avant de faire ceci, assurez-vous que votre serveur soit correctement configuré en ce qui concerne la sécurité et les restrictions d'accès.

Le script apachectl est conçu pour fonctionner comme un script d'initialisation SysV standard ; il accepte les arguments start, restart, et stop et les traduit en signaux appropriés pour httpd, et il suffit en général d'installer un lien vers apachectl dans le répertoire d'initialisation approprié. Mais prenez soin de vérifier les besoins exacts de votre système en la matière.

Informations supplémentaires

Des informations supplémentaires à propos des options en ligne de commande de httpd et apachectl ainsi que d'autres programmes support inclus dans la distribution sont disponibles sur la page Le serveur et ses programmes support. Il existe aussi une documentation sur tous les modules inclus dans la distribution Apache et les directives qu'ils supportent.


Arrêt et redémarrage du serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Arrêt et redémarrage du serveur HTTP Apache

Ce document couvre l'arrêt et le redémarrage du serveur HTTP Apache sur les systèmes Unix et similaires. Les utilisateurs de Windows NT, 2000 and XP doivent consulter Exécuter httpd en tant que service et les utilisateurs de Windows 9x et ME doivent consulter Exécuter httpd comme une application de type console pour plus d'informations sur le contrôle de httpd à partir de ces plateformes.

Voir aussi

  • httpd
  • apachectl
  • Démarrage

Introduction

Afin d'arrêter ou redémarrer le serveur HTTP Apache, vous devez envoyer un signal aux processus httpd en cours d'exécution. Les signaux peuvent être envoyés de deux manières. La première méthode consiste à utiliser la commande unix kill pour envoyer directement des signaux aux processus. Vous pouvez remarquer que plusieurs processus httpd s'exécutent sur votre système, mais il vous suffit d'envoyer les signaux au processus parent, dont le PID est enregistré dans le fichier précisé par la directive PidFile. Autrement dit, vous n'aurez jamais besoin d'envoyer des signaux à aucun des processus enfants, mais seulement au processus parent. Quatre types de signaux peuvent être envoyés au processus parent : TERM, USR1, HUP, et WINCH, qui seront décrit plus loin.

Pour envoyer un signal au processus parent, vous devez entrer une commande du style :

kill -TERM `cat /usr/local/apache2/logs/httpd.pid`

La seconde méthode permettant d'envoyer des signaux aux processus httpd consiste à utiliser les options stop, restart, graceful et graceful-stop du commutateur -k de la ligne de commande comme décrit ci-dessous. Ce sont des arguments du binaire httpd, mais il est recommandé de les utiliser avec le script de contrôle apachectl, qui se chargera de les passer à httpd.

Après avoir envoyé un signal à httpd, vous pouvez suivre le cours de son action en entrant :

tail -f /usr/local/apache2/logs/error_log

Adaptez ces exemples en fonction de la définition de vos directives ServerRoot et PidFile.

Arrêter immédiatement

Signal: TERM
apachectl -k stop

A la réception du signal TERM ou stop, le processus parent tente immédiatement de tuer tous ses processus enfants. Cela peut durer plusieurs secondes. Après cela, le processus parent lui-même se termine. Toutes les requêtes en cours sont terminées, et plus aucune autre n'est traitée.

Redémarrage en douceur

Signal: USR1
apachectl -k graceful

A la réception du signal USR1 ou graceful, le processus parent envoie aux processus enfants l'ordre de se terminer une fois leur requête courante traitée (ou de se terminer immédiatement s'ils n'ont plus rien à traiter). Le processus parent relit ses fichiers de configuration et réouvre ses fichiers de log. Chaque fois qu'un enfant s'éteint, le processus parent le remplace par un processus enfant de la nouvelle génération de la configuration, et celui-ci commence immédiatement à traiter les nouvelles requêtes.

Ce code est conçu pour toujours respecter la directive de contrôle de processus des modules MPMs, afin que les nombres de processus et de threads disponibles pour traiter les demandes des clients soient maintenus à des valeurs appropriées tout au long du processus de démarrage. En outre, il respecte la directive StartServers de la manière suivante : si après une seconde au moins StartServers nouveaux processus enfants n'ont pas été créés, un nombre suffisant de processus supplémentaires est créé pour combler le manque. Ainsi le code tente de maintenir à la fois le nombre approprié de processus enfants en fonction de la charge du serveur, et le nombre de processus défini par la directive StartServers.

Les utilisateurs du module mod_status noteront que les statistiques du serveur ne sont pas remises à zéro quand un signal USR1 est envoyé. Le code a été conçu à la fois pour minimiser la durée durant laquelle le serveur ne peut pas traiter de nouvelles requêtes (elle sont mises en file d'attente par le système d'exploitation, et ne sont ainsi jamais perdues) et pour respecter vos paramètres de personnalisation. Pour y parvenir, il doit conserver le tableau utilisé pour garder la trace de tous les processus enfants au cours des différentes générations.

Dans son état des processus, le module status utilise aussi un caractère G afin d'indiquer quels processus enfants ont encore des traitements de requêtes en cours débutés avant que l'ordre graceful restart ne soit donné.

Pour l'instant, il est impossible pour un script de rotation des logs utilisant USR1 de savoir de manière certaine si tous les processus enfants inscrivant des traces de pré-redémarrage sont terminés. Nous vous suggérons d'attendre un délai suffisant après l'envoi du signal USR1 avant de faire quoi que ce soit avec les anciens logs. Par exemple, si la plupart de vos traitements durent moins de 10 minutes pour des utilisateurs empruntant des liaisons à faible bande passante, alors vous devriez attendre 15 minutes avant de faire quoi que ce soit avec les anciens logs.

Lorsque vous initiez un redémarrage, une vérification de la syntaxe est tout d'abord effectuée, afin de s'assurer qu'il n'y a pas d'erreurs dans les fichiers de configuration. Si votre fichier de configuration comporte des erreurs de syntaxe, vous recevrez un message d'erreur les concernant, et le serveur refusera de redémarrer. Ceci permet d'éviter la situation où un serveur a été arrêté et ne peut plus redémarrer, et où vous vous retrouvez avec un serveur hors-service.

Ceci ne garantit pas encore que le serveur va redémarrer correctement. Pour vérifier la sémantique des fichiers de configuration en plus de leur syntaxe, vous pouvez essayer de démarrer httpd sous un utilisateur non root. S'il n'y a pas d'erreur, il tentera d'ouvrir ses sockets et ses fichiers de log et échouera car il n'a pas les privilèges root (ou parce que l'instance actuelle de httpd est déjà associée à ces ports). S'il échoue pour toute autre raison, il y a probablement une erreur dans le fichier de configuration et celle-ci doit être corrigée avant de lancer le redémarrage en douceur.

Redémarrer immédiatement

Signal: HUP
apachectl -k restart

A la réception du signal HUP ou restart, le processus parent tue ses processus enfants comme pour le signal TERM, mais le processus parent ne se termine pas. Il relit ses fichiers de configuration, et réouvre ses fichiers de log. Puis il donne naissance à un nouveau jeu de processus enfants et continue de traiter les requêtes.

Les utilisateurs du module mod_status noteront que les statistiques du serveur sont remises à zéro quand un signal HUP est envoyé.

Comme dans le cas d'un redémarrage "graceful", une vérification de la syntaxe est effectuée avant que le redémarrage ne soit tenté. Si votre fichier de configuration comporte des erreurs de syntaxe, le redémarrage ne sera pas effectué, et vous recevrez un message concernant ces erreurs.

Arrêt en douceur

Signal : WINCH
apachectl -k graceful-stop

A la réception du signal WINCH ou graceful-stop, le processus parent ordonne à ses processus enfants de s'arrêter après le traitement de leur requête en cours (ou de s'arrêter immédiatement s'ils n'ont plus de requête à traiter). Le processus parent va alors supprimer son fichier PidFile et cesser l'écoute de tous ses ports. Le processus parent va continuer à s'exécuter, et va surveiller les processus enfants qui ont encore des requêtes à traiter. Lorsque tous les processus enfants ont terminé leurs traitements et se sont arrêtés ou lorsque le délai spécifié par la directive GracefulShutdownTimeout a été atteint, le processus parent s'arrêtera à son tour. Si ce délai est atteint, tout processus enfant encore en cours d'exécution se verra envoyer le signal TERM afin de le forcer à s'arrêter.

L'envoi du signal TERM va arrêter immédiatement les processus parent et enfants en état "graceful". Cependant, comme le fichier PidFile aura été supprimé, vous ne pourrez pas utiliser apachectl ou httpd pour envoyer ce signal.

Le signal graceful-stop vous permet d'exécuter simultanément plusieurs instances de httpd avec des configurations identiques. Ceci s'avère une fonctionnalité puissante quand vous effectuez des mises à jour "en douceur" de httpd ; cependant, cela peut aussi causer des blocages fatals et des situations de compétition (race conditions) avec certaines configurations.

On a pris soin de s'assurer que les fichiers sur disque comme les fichiers verrou (Mutex) et les fichiers socket Unix (ScriptSock) contiennent le PID du serveur, et coexistent sans problème. Cependant, si une directive de configuration, un module tiers ou une CGI résidente utilise un autre verrou ou fichier d'état sur disque, il faut prendre soin de s'assurer que chaque instance de httpd qui s'exécute n'écrase pas les fichiers des autres instances.

Vous devez aussi prendre garde aux autres situations de compétition, comme l'enregistrement des logs avec un transfert de ceux-ci via un pipe vers le programme rotatelogs. Plusieurs instances du programme rotatelogs qui tentent d'effectuer une rotation des mêmes fichiers de log en même temps peuvent détruire mutuellement leurs propres fichiers de log.


Fichiers de configuration - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Fichiers de configuration

Ce document décrit les fichiers utilisés pour configurer le Serveur HTTP Apache.

Fichiers de configuration principaux

Modules Apparentés Directives Apparentées
  • mod_mime
  • <IfDefine>
  • Include
  • TypesConfig

La configuration du serveur HTTP Apache est effectuée en plaçant des directives dans des fichiers de configuration au format texte. Le fichier de configuration principal se nomme en général httpd.conf. La localisation de ce fichier est définie à la compilation, mais peut être redéfinie à l'aide de l'option de ligne de commande -f. En outre, d'autres fichiers de configuration peuvent être ajoutés à l'aide de la directive Include, et des caractères de remplacement peuvent être utilisés pour inclure de nombreux fichiers de configuration. Des directives de tous types peuvent être placées dans chacun de ces fichiers de configuration. Les modifications dans les fichiers de configuration principaux ne sont prises en compte par httpd que lorsque le serveur est démarré ou redémarré.

Le serveur lit aussi un fichier contenant les types de document mime; ce fichier est défini par la directive TypesConfig, et se nomme mime.types par défaut.

Syntaxe des fichiers de configuration

Les fichiers de configuration de httpd contiennent une directive par ligne. On peut utiliser l'anti-slash "\" comme dernier caractère d'une ligne pour indiquer que la directive continue à la ligne suivante. Il ne doit y avoir aucun caractère ni espace entre l'anti-slash et la fin de la ligne.

Les arguments des directives sont séparés les uns des autres par des espaces. Si un argument contient des espaces, il doit être entouré de guillemets.

Les directives dans les fichiers de configuration ne sont pas sensibles à la casse, mais leurs arguments le sont souvent. Les lignes qui débutent par le caractère "#" sont interprétées comme des commentaires, et sont ignorées. Les commentaires ne doivent pas apparaître sur la même ligne qu'une directive de configuration. Les espaces précédant une directive sont ignorés; vous pouvez par conséquent indenter les directives afin d'améliorer la lisibilité. Les lignes vides sont aussi ignorées.

Les valeurs des variables d'environnement ou des variables définies via la directive Define peuvent être utilisées dans le fichier de configuration en utilisant la syntaxe ${VAR}. Si "VAR" est le nom d'une variable valide, la valeur de la variable est alors substituée à la chaîne ${VAR}, et le processus de lecture du fichier de configuration continue comme si la chaîne correspondant à la valeur de la variable s'y était trouvée littéralement. Les variables définies via la directive Define l'emportent sur les autres variables d'environnement du shell. Si la variable "VAR" n'est pas trouvée, la chaîne ${VAR} n'est pas modifiée, et un avertissement est enregistré dans le journal. Le caractère ":" est interdit dans les noms de variables afin d'éviter tout conflit avec la syntaxe de la directive RewriteMap.

Seules les variables d'environnement du shell définies avant le démarrage du serveur peuvent être utilisées dans les extensions. Les variables d'environnement définies dans le fichier de configuration lui-même, par exemple avec SetEnv, prennent effet trop tard pour pouvoir être utilisées dans les extensions au sein du fichier de configuration.

La longueur maximale d'une ligne dans un fichier de configuration normal, après substitution des variables et fusion des lignes interrompues, est approximativement de 16 Mo. Dans les fichiers .htaccess, la longueur maximale est de 8190 caractères.

Vous pouvez vérifier l'absence d'erreurs de syntaxe dans vos fichiers de configuration sans démarrer le serveur à l'aide de la commande apachectl configtest ou de l'option de ligne de commande -t.

Vous pouvez utiliser la définition -DDUMP_CONFIG de mod_info pour afficher la configuration avec tous les fichiers inclus et les variables d'environnement évaluées, tous les commentaires et les sections <IfDefine> et <IfModule> non actives ayant été supprimés. Cependant, la sortie ne reflète pas les fusions ou écrasements pouvant intervenir en cas de définitions multiples de directives.

Modules

Modules Apparentés Directives Apparentées
  • mod_so
  • <IfModule>
  • LoadModule

httpd est un serveur modulaire. Ceci implique que seules les fonctionnalités les plus courantes sont incluses dans le serveur de base. Les fonctionnalités étendues sont fournies à l'aide de modules qui peuvent être chargés dans httpd. Par défaut, un jeu de modules de base est inclus dans le serveur à la compilation. Si le serveur est compilé de façon à utiliser les modules chargés dynamiquement, alors les modules peuvent être compilés séparément et chargés à n'importe quel moment à l'aide de la directive LoadModule. Dans le cas contraire, httpd doit être recompilé pour ajouter ou supprimer des modules. Les directives de configuration peuvent être incluses de manière conditionnelle selon la présence ou l'absence d'un module particulier en les plaçant dans un bloc <IfModule>.

Pour voir quels modules ont été compilés avec le serveur, vous pouvez utiliser l'option de ligne de commande -l.

Portée des directives

Modules Apparentés Directives Apparentées
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <Location>
  • <LocationMatch>
  • <VirtualHost>

Les directives placées dans les fichiers de configuration principaux s'appliquent au serveur dans son ensemble. Si vous souhaitez modifier la configuration d'une partie du serveur seulement, vous pouvez limiter la portée de vos directives en les plaçant dans une section <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, ou <LocationMatch>. Ces sections limitent le champ d'application des directives qu'elles contiennent à des URls ou des portions du système de fichiers particulières. Elles peuvent aussi être imbriquées, ce qui permet une configuration très fine.

httpd peut servir simultanément de nombreux sites web au travers des Hôtes Virtuels. La portée des directives peut ainsi être limitée en les plaçant dans des sections <VirtualHost>, afin qu'elles ne s'appliquent qu'aux requêtes pour un site web particulier.

Bien que la plupart des directives puissent être placées dans chacune de ces sections, certaines d'entre elles n'ont aucun sens dans certains contextes. Par exemple, les directives qui contrôlent la création des processus n'ont de sens que dans le contexte du serveur principal. Pour déterminer quelles directives peuvent être placées dans quelles sections, consultez le Contexte de la directive. Pour plus d'informations, nous fournissons des détails dans Comment fonctionnent les sections Directory, Location et Files.

Fichiers .htaccess

Modules Apparentés Directives Apparentées
  • AccessFileName
  • AllowOverride

httpd permet la gestion décentralisée de la configuration via des fichiers spéciaux placés dans l'arborescence du site web. Ces fichiers spéciaux se nomment en général .htaccess, mais tout autre nom peut être spécifié à l'aide de la directive AccessFileName. Les directives placées dans les fichiers .htaccess s'appliquent au répertoire dans lequel vous avez placé le fichier, ainsi qu'à tous ses sous-répertoires. La syntaxe des fichiers .htaccess est la même que celle des fichiers de configuration principaux. Comme les fichiers .htaccess sont lus à chaque requête, les modifications de ces fichiers prennent effet immédiatement.

Pour déterminer quelles directives peuvent être placées dans les fichiers .htaccess, consultez le Contexte de la directive. L'administrateur du serveur peut contrôler quelles directives peuvent être placées dans les fichiers .htaccess en définissant la directive AllowOverride dans les fichiers de configuration principaux.

Pour plus d'informations sur les fichiers .htaccess, se référer au tutoriel .htaccess.


Sections de configuration - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Sections de configuration

Les directives des fichiers de configuration peuvent s'appliquer au serveur dans son ensemble, ou seulement à des répertoires, fichiers, hôtes, ou URLs particuliers. Ce document décrit comment utiliser les conteneurs de sections de configuration ou les fichiers .htaccess pour modifier la portée des directives de configuration.

Types de conteneurs de sections de configuration

Modules Apparentés Directives Apparentées
  • core
  • mod_version
  • mod_proxy
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <If>
  • <IfDefine>
  • <IfModule>
  • <IfVersion>
  • <Location>
  • <LocationMatch>
  • <MDomainSet>
  • <Proxy>
  • <ProxyMatch>
  • <VirtualHost>

Il existe deux grands types de conteneurs. La plupart des conteneurs sont évalués pour chaque requête. Les directives qu'ils contiennent s'appliquent seulement aux requêtes qui sont concernées par le conteneur. En revanche, les conteneurs <IfDefine>, <IfModule>, et <IfVersion> sont évalués seulement au démarrage et au redémarrage du serveur. Si leurs conditions sont vérifiées au démarrage, les directives qu'ils contiennent s'appliqueront à toutes les requêtes. Si leurs conditions ne sont pas vérifiées, les directives qu'ils contiennent seront ignorées.

Le conteneur <IfDefine> contient des directives qui ne seront appliquées que si un paramètre approprié a été défini dans la ligne de commande de httpd. Par exemple, avec la configuration suivante, toutes les requêtes seront redirigées vers un autre site si le serveur est démarré en utilisant la ligne de commande : httpd -DClosedForNow:

<IfDefine ClosedForNow>
    Redirect "/" "http://otherserver.example.com/"
</IfDefine>

Le conteneur <IfModule> est similaire; les directives qu'il contient ne s'appliqueront que si un module particulier est disponible au niveau du serveur. Le module doit être soit compilé statiquement dans le serveur, soit dynamiquement et dans ce cas, la ligne LoadModule correspondante doit apparaître plus haut dans le fichier de configuration. Ce conteneur ne doit être utilisé que dans le cas où votre fichier de configuration doit fonctionner indépendamment de la présence ou de l'absence de certains modules. Il ne doit pas contenir de directives que vous souhaitez voir s'appliquer systématiquement, car vous pouvez perdre ainsi de précieux messages d'erreur à propos de modules manquants.

Dans l'exemple suivant, la directive MimeMagicFile ne s'appliquera que si le module mod_mime_magic est disponible.

<IfModule mod_mime_magic.c>
    MimeMagicFile "conf/magic"
</IfModule>

Le conteneur <IfVersion> est similaire aux conteneurs <IfDefine> et <IfModule>; les directives qu'il contient ne s'appliqueront que si une version particulière du serveur s'exécute. Ce conteneur a été conçu pour une utilisation dans les suites de tests et les grands réseaux qui doivent prendre en compte différentes versions et configurations de httpd.

<IfVersion >= 2.4>
    # les directives situées ici ne s'appliquent que si la version

    # est supérieure ou égale à 2.4.0.
</IfVersion>

<IfDefine>, <IfModule>, et <IfVersion> peuvent inverser leur test conditionnel en le faisant précéder d'un "!". De plus, ces sections peuvent être imbriquées afin de définir des restrictions plus complexes.

Système de fichiers, arborescence du site web et expressions booléennes

Les conteneurs de sections de configuration les plus couramment utilisés sont ceux qui modifient la configuration de points particuliers du système de fichiers ou de l'arborescence du site web. Tout d'abord, il est important de comprendre la différence entre les deux. Le système de fichiers est une vue de vos disques tels qu'ils sont perçus par votre système d'exploitation. Par exemple, avec une installation par défaut, Apache httpd est situé dans /usr/local/apache2 pour le système de fichiers UNIX, ou "c:/Program Files/Apache Group/Apache2" pour le système de fichiers Windows. (Notez que des slashes directs doivent toujours être utilisés comme séparateur de chemin dans les fichiers de configuration d'Apache httpd, même sous Windows.) Quant à l'arborescence du site web, il s'agit d'une vue de votre site tel que présenté par le serveur web et perçue par le client. Ainsi le chemin /dir/ dans l'arborescence du site web correspond au chemin /usr/local/apache2/htdocs/dir/ dans le système de fichiers pour une installation d'Apache httpd par défaut sous UNIX. En outre, l'arborescence du site web n'a pas besoin de correspondre en permanence au système de fichiers, car les pages web peuvent être générées dynamiquement à partir de bases de données ou d'autres emplacements.

Conteneurs de système de fichiers

Les conteneurs <Directory> et <Files>, ainsi que leurs équivalents acceptant les expressions rationnelles, appliquent des directives à certaines parties du système de fichiers. Les directives contenues dans une section <Directory> s'appliquent au répertoire précisé, ainsi qu'à tous ses sous-répertoires et aux fichiers que ces derniers contiennent. Le même effet peut être obtenu en utilisant les fichiers .htaccess. Par exemple, avec la configuration suivante, l'indexation sera activée pour le répertoire /var/web/dir1 et tous ses sous-répertoires.

<Directory "/var/web/dir1">
    Options +Indexes
</Directory>

Les directives contenues dans une section <Files> s'appliquent à tout fichier avec le nom spécifié, quel que soit le répertoire dans lequel il se trouve. Ainsi par exemple, les directives de configuration suivantes, si elles sont placées dans la section principale du fichier de configuration, vont interdire l'accès à tout fichier nommé private.html quel que soit l'endroit où il se trouve.

<Files "private.html">
    Require all denied
</Files>

Pour faire référence à des fichiers qui se trouvent en des points particuliers du système de fichiers, les sections <Files> et <Directory> peuvent être combinées. Par exemple, la configuration suivante va interdire l'accès à /var/web/dir1/private.html, /var/web/dir1/subdir2/private.html, /var/web/dir1/subdir3/private.html, ainsi que toute instance de private.html qui se trouve dans l'arborescence /var/web/dir1/.

<Directory "/var/web/dir1">
    <Files "private.html">
        Require all denied
    </Files>
</Directory>

Conteneurs de l'arborescence du site web

le conteneur <Location> et son équivalent acceptant les expressions rationnelles, modifient quant à eux la configuration de parties de l'arborescence du site web. Par exemple, la configuration suivante interdit l'accès à toute URL dont la partie chemin commence par /private. En particulier, l'interdiction s'appliquera aux requêtes pour : http://yoursite.example.com/private, http://yoursite.example.com/private123, et http://yoursite.example.com/private/dir/file.html ainsi qu'à toute requête commençant par la chaîne de caractères /private.

<LocationMatch "^/private">
    Require all denied
</LocationMatch>

Le conteneur <Location> n'a pas besoin de faire référence à un élément du système de fichiers. Par exemple, l'exemple suivant montre comment faire référence à une URL particulière vers un gestionnaire interne du serveur HTTP Apache fourni par le module mod_status. Il n'est pas nécessaire de trouver un fichier nommé server-status dans le système de fichiers.

<Location "/server-status">
    SetHandler server-status
</Location>

Espace web imbriqué

Pour contrôler deux URLs imbriquées, on doit tenir compte de l'ordre dans lequel certaines sections ou directives sont évaluées. Pour <Location>, on doit avoir :

<Location "/foo">
</Location>
<Location "/foo/bar">
</Location>

Les directives <Alias>, quant à elles, sont évaluées vice-versa :

Alias "/foo/bar" "/srv/www/uncommon/bar"
Alias "/foo" "/srv/www/common/foo"

Ceci est aussi vrai pour les directives ProxyPass :

ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On

Caractères de remplacement et expressions rationnelles

Les conteneurs <Directory>, <Files>, et <Location> peuvent utiliser des caractères de remplacement de style shell comme dans la fonction fnmatch de la bibliothèque C standard. Le caractère "*" correspond à toute séquence de caractères, "?" à un caractère seul, et "[seq]" à tout caractère contenu dans seq. Le caractère "/" ne peut pas faire l'objet d'un remplacement; il doit être spécifié explicitement.

Si une définition des critères de correspondance encore plus souple est nécessaire, chaque conteneur possède son équivalent acceptant les expressions rationnelles : <DirectoryMatch>, <FilesMatch>, et <LocationMatch> acceptent les expressions rationnelles compatibles Perl pour définir les critères de correspondance. Mais voyez plus loin la section à propos de la combinaison des sections de configuration pour comprendre comment l'utilisation de conteneurs avec des expressions rationnelles va modifier la manière dont les directives sont appliquées.

Un conteneur qui modifie la configuration de tous les répertoires utilisateurs à l'aide de caractères de remplacement mais sans utiliser les expressions rationnelles pourrait ressembler à ceci :

<Directory "/home/*/public_html">
    Options Indexes
</Directory>

Avec les conteneurs utilisant les expressions rationnelles, on peut interdire l'accès à de nombreux types de fichiers d'images simultanément :

+<FilesMatch "\.(?i:gif|jpe?g|png)$">
    Require all denied
</FilesMatch>

Les expressions rationnelles contenant des groupes nommés et des références arrières sont ajoutées à l'environnement avec leur nom en majuscules. Ceci permet de référencer des éléments de chemins de fichiers et d'URLs depuis une expression et au sein de modules comme mod_rewrite.

<DirectoryMatch "^/var/www/combined/(?<SITENAME>[^/]+)">
    require ldap-group "cn=%{env:MATCH_SITENAME},ou=combined,o=Example"
</DirectoryMatch>

Expressions booléennes

La directive <If> permet de modifier la configuration en fonction d'une condition qui peut être définie sous la forme d'une expression booléenne. Dans l'exemple suivant, l'accès est interdit si l'en-tête HTTP Referer ne commence pas par "http://www.example.com/".

<If "!(%{HTTP_REFERER} -strmatch 'http://www.example.com/*')">
    Require all denied
</If>

Que faut-il utiliser et quand ?

Choisir entre des conteneurs de système de fichiers et des conteneurs d'arborescence du site web est vraiment très simple. Pour appliquer des directives à des objets qui résident dans le système de fichiers, utilisez toujours un conteneur <Directory> ou <Files>. Pour appliquer des directives à des objets qui ne résident pas dans le système de fichiers (comme une page web générée par une base de données), utilisez un conteneur <Location>.

Il ne faut jamais utiliser un conteneur <Location> pour restreindre l'accès à des objets du système de fichiers, car plusieurs localisations de l'arborescence du site web (URLs) peuvent correspondre à la même localisation du système de fichier, ce qui peut permettre de contourner vos restrictions. Par exemple, imaginez la configuration suivante :

<Location "/dir/">
    Require all denied
</Location>

Elle fonctionne correctement si la requête appelle http://yoursite.example.com/dir/. Mais que va-t-il se passer si votre système de fichiers est insensible à la casse ? Votre restriction va pouvoir être tout simplement contournée en envoyant une requête sur http://yoursite.example.com/DIR/. Le conteneur <Directory>, quant à lui, s'appliquera à tout contenu servi à partir de cette localisation, sans tenir compte de la manière dont il est appelé. (Les liens du système de fichiers constituent une exception. Le même répertoire peut être placé dans plusieurs parties du système de fichiers en utilisant des liens symboliques. Le conteneur <Directory> va suivre le lien symbolique sans modifier le nom du chemin. Par conséquent, pour plus de sécurité, les liens symboliques doivent être désactivés à l'aide de la directive Options appropriée.)

Si vous pensez que vous n'êtes pas concerné par ce problème parceque vous utilisez un système de fichiers sensible à la casse, gardez à l'esprit qu'il y a de nombreuses autres manières pour faire correspondre plusieurs localisations de l'arborescence du site web à la même localisation du système de fichiers. C'est pourquoi vous devez autant que possible toujours utiliser les conteneurs de système de fichiers. Il y a cependant une exception à cette règle. Placer des restrictions de configuration dans un conteneur <Location "/"> est tout à fait sans rique car ce conteneur va s'appliquer à toutes les requêtes sans tenir compte de l'URL spécifique.

Imbrication des sections

Certains types de sections peuvent être imbriqués : d'une part, on peut utiliser les sections <Files> à l'intérieur des sections <Directory>, d'autre part, on peut utiliser les directives <If> à l'intérieur des sections <Directory>, <Location> et <Files> (mais pas à l'intérieur d'une autre section <If>). Les valeurs des expressions rationnelles correspondant aux sections nommées se comportent de manière identique.

Les sections imbriquées sont fusionnées après les sections non-imbriquées de même type.

Hôtes virtuels

Le conteneur <VirtualHost> contient des directives qui s'appliquent à des hôtes spécifiques. Ceci s'avère utile pour servir des hôtes multiples à partir de la même machine, chacun d'entre eux possédant une configuration différente. Pour de plus amples informations, voir la Documentation sur les hôtes virtuels.

Mandataire

Les conteneurs <Proxy> et <ProxyMatch> appliquent les directives de configuration qu'ils contiennent uniquement aux sites qui correspondent à l'URL spécifiée et auxquels on a accédé via le serveur mandataire du module mod_proxy. Par exemple, la configuration suivante n'autorisera qu'un sous-ensemble de clients à accéder au site www.example.com en passant par le serveur mandataire :

<Proxy "http://www.example.com/*">
    Require host yournetwork.example.com
</Proxy>

Quelles sont les directives autorisées ?

Pour déterminer quelles sont les directives autorisées pour tel type de section de configuration, vérifiez le Contexte de la directive. Tout ce qui est autorisé dans les sections <Directory> l'est aussi d'un point de vue syntaxique dans les sections <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, <LocationMatch>, <Proxy>, et <ProxyMatch>. Il y a cependant quelques exceptions :

  • La directive AllowOverride ne fonctionne que dans les sections <Directory>.
  • Les Options FollowSymLinks et SymLinksIfOwnerMatch ne fonctionnent que dans les sections <Directory> ou les fichiers .htaccess.
  • La directive Options ne peut pas être utilisée dans les sections <Files> et <FilesMatch>.

Comment les sections sont combinées entre elles

Les sections de configuration sont appliquées dans un ordre très particulier. Il est important de savoir comment cet ordre est défini car il peut avoir des effets importants sur la manière dont les directives de configuration sont interprétées.

L'ordre dans lequel les sections sont combinées est :

  1. Les sections <Directory> (à l'exception des expressions rationnelles) et les fichiers .htaccess sont appliqués simultanément (avec la possibilité pour .htaccess, s'il y est autorisé, de prévaloir sur <Directory>)
  2. Les sections <DirectoryMatch> (et <Directory "~">)
  3. Les sections <Files> et <FilesMatch> sont appliquées simultanément
  4. Les sections <Location> et <LocationMatch> sont appliquées simultanément
  5. Les directives <If>

Quelques remarques importantes :

  • Mises à part les sections <Directory>, dans chaque groupe, les sections sont traitées selon l'ordre dans lequel elles apparaissent dans les fichiers de configuration. Par exemple, une requête pour /foo correspondra à <Location "/foo/bar"> et <Location "/foo"> (dans ce cas le groupe 4) : les deux sections seront évaluées mais selon l'ordre dans lequel elles apparaissent dans le fichier de configuration..
  • Les sections <Directory> (groupe 1 ci-dessus) sont traitées dans l'ordre du répertoire le plus court vers le plus long. Par exemple, <Directory "/var/web/dir"> sera traité avant <Directory "/var/web/dir/subdir">.
  • Si plusieurs sections <Directory> s'appliquent au même répertoire, elles sont traitées selon l'ordre dans lequel elles apparaissent dans le fichier de configuration.
  • Les sections de configuration incluses via la directive Include sont traitées comme si elles se trouvaient réellement dans le fichier qui les inclut à la position de la directive Include.
  • Les sections situées à l'intérieur de sections <VirtualHost> sont appliquées après les sections correspondantes situées en dehors de la définition de l'hôte virtuel, ce qui permet à l'hôte virtuel de prévaloir sur la configuration du serveur principal.
  • Quand la requête est servie par le module mod_proxy, le conteneur <Proxy> prend la place du conteneur <Directory> dans l'ordre de traitement.

Note technique

Une séquence <Location>/<LocationMatch> est réellement traitée juste avant la phase de traduction du nom (où Aliases et DocumentRoots sont utilisés pour faire correspondre les URLs aux noms de fichiers). Les effets de cette séquence disparaissent totalement lorsque la traduction est terminée.

Interactions entre modules et sections de configuration

Une question se pose souvent après avoir lu comment les sections de configuration sont fusionnées : comment et quand les directives de modules particuliers comme mod_rewrite sont-elles interprétées ? La réponse n'est pas triviale et nécessite un approfondissement. Chaque module httpd gère sa propre configuration, et chacune de ses directives dans httpd.conf définit un élément de configuration dans un contexte particulier. httpd n'exécute pas un commande au moment où elle est lue.

A l'exécution, le noyau de httpd parcours les sections de configuration dans l'ordre décrit ci-dessus afin de déterminer lesquelles s'appliquent à la requête courante. Lorsqu'une première section s'applique, elle est considérée comme la configuration courante pour cette requête. Si une section suivante s'applique aussi, chaque module qui possède des directives dans chacune de ces sections a la possibilité de fusionner sa configuration entre ces deux sections. Il en résulte une troisième configuration et le processus de fusion se poursuit jusqu'à ce que toutes les sections de configuration aient été évaluées.

Après l'étape précédente, le traitement proprement dit de la requête HTTP peut commencer : chaque module peut effectuer toute tâche qui lui incombe, et pour déterminer de quelle manière dont il doit agir, il peut s'appuyer sur le noyau de httpd pour retrouver sa configuration globale issue de la fusion précédente.

Un exemple permet de mieux visualiser l'ensemble du processus. la configuration suivante utilise la directive Header du module mod_headers pour définir un en-tête HTTP spécifique. Quelle valeur httpd va-t-il affecter à l'en-tête CustomHeaderName pour une requête vers /example/index.html ?

<Directory "/">
    Header set CustomHeaderName one
    <FilesMatch ".*">
        Header set CustomHeaderName three
    </FilesMatch>
</Directory>

<Directory "/example">
    Header set CustomHeaderName two
</Directory>
  • Directory "/" s'applique, et une configuration initiale est créée qui définit l'en-tête CustomHeaderName avec la valeur one.
  • Directory "/example" s'applique, et comme mod_headers spécifie dans son code que la valeur d'un en-tête doit être écrasée si ce dernier est défini à nouveau, une nouvelle configuration est créée qui définit l'en-tête CustomHeaderName avec la valeur two.
  • FilesMatch ".*" s'applique, une nouvelle opportunité de fusion surgit, et l'en-tête CustomHeaderName est défini à la valeur three.
  • Finalement, au cours des étapes suivantes du traitement de la requête HTTP, mod_headers sera sollicité, et il se basera sur la configuration qui a défini l'en-tête CustomHeaderName à la valeur three. mod_headers utilise normalement cette configuration pour accomplir sa tâche, à savoir définir des en-têtes HTTP. Cela ne veut cependant pas dire qu'un module ne peut pas effectuer des actions plus complexes comme désactiver des directives car elle ne sont pas nécessaires ou obsolètes, etc...

Ceci est aussi vrai pour les fichiers .htaccess car ils possèdent la même priorité que les sections Directory dans l'ordre de fusion. Il faut bien comprendre que les sections de configuration comme Directory et FilesMatch ne sont pas comparables avec les directives spécifiques de modules comme Header ou RewriteRule car elles agissent à des niveaux différents.

Quelques exemples utiles

Voici un exemple imaginaire qui montre l'ordre de combinaison des sections. En supposant qu'elles s'appliquent toutes à la requête, les directives de cet exemple seront appliquées dans l'ordre suivant : A > B > C > D > E.

<Location "/">
    E
</Location>

<Files "f.html">
    D
</Files>

<VirtualHost *>
<Directory "/a/b">
    B
</Directory>
</VirtualHost>

<DirectoryMatch "^.*b$">
    C
</DirectoryMatch>

<Directory "/a/b">
    A
</Directory>

Pour un exemple plus concret, considérez ce qui suit. Sans tenir compte de toute restriction d'accès placée dans les sections <Directory>, la section <Location> sera évaluée en dernier et permettra un accès au serveur sans aucune restriction. En d'autres termes, l'ordre de la combinaison des sections est important, soyez donc prudent !

<Location "/">
    Require all granted
</Location>

# Arrghs!  Cette section <Directory> n'aura aucun effet
<Directory "/">
    <RequireAll>
        Require all granted
        Require not host badguy.example.com
    </RequireAll>
</Directory>


Guide de la mise en cache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Guide de la mise en cache

Ce document complète la documentation de référence des modules mod_cache, mod_cache_disk, mod_file_cache et du programme htcacheclean. Il décrit l'utilisation des fonctionnalités de mise en cache du serveur HTTP Apache pour accélérer les services web et proxy, tout en évitant les problèmes courants et les erreurs de configuration.

Introduction

Le serveur HTTP Apache offre tout un ensemble de fonctionnalités de mise en cache qui ont été conçues pour améliorer les performances du serveur de différentes manières.

Mise en cache HTTP à trois états RFC2616
mod_cache et son module de fournisseur mod_cache_disk proposent une mise en cache intelligente de niveau HTTP. Le contenu proprement dit est stocké dans le cache, et mod_cache vise à respecter tous les en-têtes HTTP, ainsi que les options qui contrôlent la mise en cache du contenu comme décrit dans la Section 13 de la RFC2616. mod_cache peut gérer des configurations de mise en cache simples, mais aussi complexes comme dans les cas où vous avez à faire à des contenus mandatés, à des contenus locaux dynamiques, ou lorsque vous avez besoin d'accélérer l'accès aux fichiers locaux situés sur disque supposé lent.
Mise en cache d'objets partagés de forme clé/valeur à deux états
L'API du cache d'objets partagés (socache) et ses modules de fournisseurs proposent une mise en cache d'objets partagés à base de couples clé/valeur de niveau serveur. Ces modules sont conçus pour la mise en cache de données de bas niveau comme les sessions SSL et les données d'authentification. les serveurs d'arrière-plan permettent le stockage des données au niveau serveur en mémoire partagée, ou au niveau datacenter dans un cache comme memcache ou distcache.
Mise en cache de fichiers spécialisée
mod_file_cache offre la possibilité de précharger des fichiers en mémoire au démarrage du serveur, et peut améliorer les temps d'accès et sauvegarder les gestionnaires de fichiers pour les fichiers qui font l'objet d'accès fréquents, évitant ainsi d'avoir à accéder au disque à chaque requête.

Pour tirer parti efficacement de ce document, les bases de HTTP doivent vous être familières, et vous devez avoir lu les sections Mise en correspondance des URLs avec le système de fichiers et Négociation sur le contenu du guide de l'utilisateur.

Mise en cache HTTP à trois états RFC2616

Modules Apparentés Directives Apparentées
  • mod_cache
  • mod_cache_disk
  • CacheEnable
  • CacheDisable
  • UseCanonicalName
  • CacheNegotiatedDocs

Le module mod_cache permet de tirer avantage du mécanisme de mise en cache en ligne faisant partie intégrante du protocole HTTP, et décrit dans la section 13 de la RFC2616.

A la différence d'un cache simple clé/valeur à deux états où le contenu est supprimé lorsqu'il est périmé, un cache HTTP comporte un mécanisme permettant de conserver temporairement un contenu périmé, de demander au serveur original si ce contenu périmé a été modifié, et dans le cas contraire de le rendre à nouveau valide.

Une entrée d'un cache HTTP peut se présenter sous un de ces trois états :

Frais
Si un contenu est suffisamment récent (plus jeune que sa durée de fraîcheur), il est considéré comme frais. Un cache HTTP peut servir un contenu frais sans avoir à demander quoi que ce soit au serveur d'origine.
Périmé

Si le contenu est trop ancien (plus vieux que sa durée de fraîcheur), il est considéré comme périmé. Un cache HTTP doit contacter le serveur original pour vérifier si le contenu, même s'il est périmé, est encore à jour avant de le servir au client. Soit le serveur original va répondre en envoyant un contenu de remplacement si le contenu périmé n'est plus à jour, soit dans le cas idéal il renverra un code pour signaler au cache que le contenu est encore à jour, et qu'il est inutile de le générer ou de l'envoyer à nouveau. Le contenu repasse à l'état "frais" et le cycle continue.

Le protocole HTTP permet au cache de servir des données périmées dans certaines circonstances, comme lorsqu'une tentative de rafraîchir une entrée depuis un serveur original se solde par un échec avec un code d'erreur 5xx, ou lorsqu'une autre requête est déjà en train d'essayer de rafraîchir la même entrée. Dans ces cas, un en-tête Warning est ajouté à la réponse.

Non Existent
Si le cache est plein, il se réserve la possibilité de supprimer des entrées pour faire de la place. Une entrée peut être supprimée à tout moment, qu'elle soit fraîche ou périmée. L'outil htcacheclean peut être utilisé à la demande, ou lancé en tant que démon afin de conserver la taille du cache ou le nombre d'inodes en deçà de valeurs spécifiées. Cet outil essaie cependant de supprimer les entrées périmées avant les entrées fraîches.

Le fonctionnement détaillé d'un cache HTTP est décrit dans la Section 13 de la RFC2616.

Interaction avec le serveur

Le module mod_cache interagit avec le serveur à deux niveaux possibles en fonction de la directive CacheQuickHandler :

Phase de gestion rapide

Cette phase se déroule très tôt au cours du traitement de la requête, juste après l'interprétation de cette dernière. Si le contenu se trouve dans le cache, il est servi immédiatement et pratiquement tout le reste du traitement de la requête est court-circuité.

Dans ce scénario, le cache se comporte comme s'il avait été "boulonné" à l'entrée du serveur.

Ce mode possède les meilleures performances car la majorité des traitements au niveau du serveur sont court-circuités. Cependant, il court-circuite aussi les phases d'authentification et d'autorisation du traitement au niveau du serveur, et il doit donc être utilisé avec prudence lorsque que ces phases sont importantes.

Les requêtes comportant un en-tête "Authorization" (comme par exemple l'authentification HTTP basique) ne peuvent être ni mises en cache, ni servies depuis ce dernier lorsque mod_cache s'exécute dans cette phase.

Phase de gestion normale

Cette phase se déroule très tard au cours du traitement de la requête, en fait après toutes les phases de ce traitement.

Dans ce scénario, le cache se comporte comme s'il avait été "boulonné" à la sortie du serveur.

Ce mode offre la plus grande souplesse, car il permet de faire intervenir la mise en cache en un point précisément spécifié de la chaîne de filtrage, et le contenu issu du cache peut être filtré ou personnalisé avant d'être servi au client.

Si l'URL ne se trouve pas dans le cache, mod_cache ajoutera un filtre à la chaîne de filtrage afin d'enregistrer la réponse dans le cache, puis passera la main pour permettre le déroulement normal de la suite du traitement de la requête. Si la mise en cache du contenu est autorisée, il sera enregistré dans le cache pour pouvoir être servi à nouveau ; dans le cas contraire, le contenu sera ignoré.

Si le contenu trouvé dans le cache est périmé, le module mod_cache convertit la requête en requête conditionnelle. Si le serveur original renvoie une réponse normale, elle est enregistrée dans le cache en lieu et place du contenu périmé. Si le serveur original renvoie une réponse "304 Not Modified", le contenu repasse à l'état "frais" et est servi par le filtre au lieu d'être sauvegardé.

Amélioration du taux de présence dans le cache

Lorsqu'un serveur virtuel est connu sous la forme d'un des nombreux alias du serveur, la définition de la directive UseCanonicalName à On peut augmenter de manière significative le nombre de correspondances positives dans le cache. Ceci est du au fait que la clé du cache contient le nom d'hôte du serveur virtuel. Avec UseCanonicalName positionnée à On, les hôtes virtuels possédant plusieurs noms de serveur ou alias ne généreront pas d'entités de cache différentes, et le contenu sera mis en cache en faisant référence au nom d'hôte canonique.

Durée de fraîcheur

Un contenu bien formé destiné à être mis en cache doit déclarer explicitement une durée de fraîcheur via les champs max-age ou s-maxage de l'en-tête Cache-Control, ou en incluant un en-tête Expires.

De plus, un client peut passer outre la durée de fraîcheur définie pour le serveur original en ajoutant son propre en-tête Cache-Control à la requête. Dans ce cas, c'est la durée de fraîcheur la plus basse entre la requête et la réponse qui l'emporte.

Lorsque cette durée de fraîcheur est absente de la requête ou de la réponse, une durée de fraîcheur par défaut s'applique. La durée de fraîcheur par défaut des entrées du cache est d'une heure ; elle peut cependant être facilement modifiée à l'aide de la directive CacheDefaultExpire.

Si une réponse ne contient pas d'en-tête Expires mais inclut un en-tête Last-Modified, mod_cache peut déduire une durée de fraîcheur en se basant sur une heuristique, qui peut être contrôlée via la directive CacheLastModifiedFactor.

Pour les contenus locaux, ou les contenus distants qui ne spécifient pas leur propre en-tête Expires, mod_expires permet de régler finement la durée de fraîcheur via les paramètres max-age et Expires.

On peut aussi contrôler la durée de fraîcheur maximale en utilisant la directive CacheMaxExpire.

Guide succinct des requêtes conditionnelles

Lorsqu'un contenu du cache est périmé, httpd modifie la requête pour en faire une requête conditionnelle

Lorsque la réponse originale du cache contient un en-tête ETag, mod_cache ajoute un en-tête If-None-Match à la requête envoyée au serveur d'origine. Lorsque la réponse originale du cache contient un en-tête Last-Modified, mod_cache ajoute un en-tête If-Modified-Since à la requête envoyée au serveur d'origine. Dans ces deux cas, la requête devient une requête conditionnelle.

Lorsqu'un serveur d'origine reçoit une requête conditionnelle, il vérifie si le paramètre Etag ou Last-Modified a été modifié en fonction des paramètres de la requête. Si ce n'est pas le cas, il répondra avec le message lapidaire "304 Not Modified". Ceci informe le cache que le contenu est périmé mais encore à jour, et peut être utilisé tel quel pour les prochaines requêtes jusqu'à ce qu'il atteigne à nouveau sa date de péremption.

Si le contenu a été modifié, il est servi comme s'il s'agissait d'une requête normale et non conditionnelle.

Les requêtes conditionnelles offrent deux avantages. D'une part, il est facile de déterminer si le contenu du serveur d'origine correspond à celui situé dans le cache, et ainsi d'économiser la consommation de ressources nécessaire au transfert du contenu dans son ensemble.

D'autre part, un serveur d'origine bien conçu sera configuré de telle manière que les requêtes conditionnelles nécessitent pour leur production bien moins de ressources qu'une réponse complète. Dans le cas des fichiers statiques, il suffit en général d'un appel système de type stat() ou similaire pour déterminer si la taille ou la date de modification du fichier a été modifiée. Ainsi, même un contenu local pourra être servi plus rapidement depuis le cache s'il n'a pas été modifié.

Il serait souhaitable que tous les serveurs d'origine supportent les requêtes conditionnelles, car dans le cas contraire, ils répondent comme s'il s'agissait d'une requête normale, et le cache répond comme si le contenu avait été modifié et enregistre ce dernier. Le cache se comporte alors comme un simple cache à deux état, où le contenu est servi s'il est à jour, ou supprimé dans le cas contraire.

Que peut-on mettre en cache ?

La liste complète des conditions nécessaires pour qu'une réponse puisse être enregistrée dans un cache HTTP est fournie dans la section 13.4 Response Cacheability de la RFC2616, et peut se résumer ainsi :

  1. La mise en cache doit être activée pour cette URL. Voir les directives CacheEnable et CacheDisable.
  2. La reponse doit avoir un code de statut HTTP de 200, 203, 300, 301 ou 410.
  3. La requête doit être de type HTTP GET.
  4. Si la réponse contient un en-tête "Authorization:", elle doit aussi contenir une option "s-maxage", "must-revalidate" ou "public" dans l'en-tête "Cache-Control:".
  5. Si l'URL contient une chaîne de requête (provenant par exemple d'une méthode GET de formulaire HTML), elle ne sera pas mise en cache, à moins que la réponse ne spécifie explicitement un délai d'expiration via un en-tête "Expires:" ou une directive max-age ou s-maxage de l'en-tête "Cache-Control:" comme indiqué dans les sections 13.2.1. et 13.9 de la RFC2616.
  6. Si la réponse a un statut de 200 (OK), elle doit aussi contenir au moins un des en-têtes "Etag", "Last-Modified" ou "Expires", ou une directive max-age ou s-maxage de l'en-tête "Cache-Control:", à moins que la directive CacheIgnoreNoLastMod ne précise d'autres contraintes.
  7. Si la réponse contient l'option "private" dans un en-tête "Cache-Control:", elle ne sera pas mise en cache à moins que la directive CacheStorePrivate ne précise d'autres contraintes.
  8. De même, si la réponse contient l'option "no-store" dans un en-tête "Cache-Control:", elle ne sera pas mise en cache à moins que la directive CacheStoreNoStore n'ait été utilisée.
  9. Une réponse ne sera pas mise en cache si elle comporte un en-tête "Vary:" contenant le caractère "*" qui correspond à toute chaîne de caractères.

Qu'est ce qui ne doit pas être mis en cache ?

Le client qui crée la requête ou le serveur d'origine qui génère la réponse doit être à même de déterminer si le contenu doit pouvoir être mis en cache ou non en définissant correctement l'en-tête Cache-Control, et mod_cache sera alors en mesure de satisfaire les souhaits du client ou du serveur de manière appropriée.

Les contenus qui varient au cours du temps, ou en fonction de particularités de la requête non prises en compte par la négociation HTTP ne doivent pas être mis en cache. Ce type de contenu doit se déclarer lui-même "à ne pas mettre en cache" via l'en-tête Cache-Control.

Si le contenu change souvent, suite par exemple à une durée de fraîcheur de l'ordre de la minute ou de la seconde, il peut tout de même être mis en cache, mais il est alors fortement souhaitable que le serveur d'origine supporte correctement les requêtes conditionnelles afin que des réponses complètes ne soient pas systématiquement générées.

Un contenu qui varie en fonction d'en-têtes de requête fournis par le client peut être mis en cache, sous réserve d'une utilisation appropriée de l'en-tête de réponse Vary.

Contenu variable et/ou négocié

Lorsque le serveur d'origine est configuré pour servir des contenus différents en fonction de la valeur de certains en-têtes de la requête, par exemple pour servir une ressource en plusieurs langages à partir d'une seule URL, le mécanisme de mise en cache d'HTTP permet de mettre en cache plusieurs variantes de la même page à partir d'une seule URL.

Pour y parvenir, le serveur d'origine ajoute un en-tête Vary pour indiquer quels en-têtes doivent être pris en compte par un cache pour déterminer si deux variantes sont différentes l'une de l'autre.

Si par exemple, une réponse est reçue avec l'en-tête Vary suivant,

Vary: negotiate,accept-language,accept-charset

mod_cache ne servira aux demandeurs que le contenu mis en cache qui correspond au contenu des en-têtes accept-language et accept-charset de la requête originale.

Plusieurs variantes d'un contenu peuvent être mises en cache simultanément ; mod_cache utilise l'en-tête Vary et les valeurs correspondantes des en-têtes de la requête spécifiés dans ce dernier pour déterminer quelle variante doit être servie au client.

Exemples de configuration du cache

Modules Apparentés Directives Apparentées
  • mod_cache
  • mod_cache_disk
  • mod_cache_socache
  • mod_socache_memcache
  • CacheEnable
  • CacheRoot
  • CacheDirLevels
  • CacheDirLength
  • CacheSocache

Mise en cache sur disque

Le module mod_cache s'appuie sur des implémentations de stockage sous-jacentes spécifiques pour gérer le cache ; à ce titre, mod_cache_disk fournit le support de la mise en cache sur disque.

En général, le module se configure comme suit :

CacheRoot   "/var/cache/apache/"
CacheEnable disk /
CacheDirLevels 2
CacheDirLength 1

Il est important de savoir que, les fichiers mis en cache étant stockés localement, la mise en cache par l'intermédiaire du système d'exploitation sera en général aussi appliquée à leurs accès. Si bien que même si les fichiers sont stockés sur disque, s'il font l'objet d'accès fréquents, il est probable que le système d'exploitation s'appliquera à ce qu'ils soient servis à partir de la mémoire.

Comprendre le stockage dans le cache

Pour stocker des entités dans le cache, le module mod_cache_disk crée une empreinte (hash) de 22 caractères de l'URL qui a fait l'objet d'une requête. Cette empreinte comprend le nom d'hôte, le protocole, le port, le chemin et tout argument de type CGI associé à l'URL, ainsi que les éléments spécifiés dans l'en-tête Vary afin d'être sur que plusieurs URLs n'interfèrent pas entre elles.

Chaque position de l'empreinte peut contenir un caractère choisi parmi 64 caractères différents, il y a donc 64^22 possibilités pour une empreinte. Par exemple, une URL peut posséder l'empreinte xyTGxSMO2b68mBCykqkp1w. Cette empreinte est utilisée pour préfixer les noms de fichiers spécifiques à cette URL à l'intérieur du cache; cependant, elle est tout d'abord placée dans les répertoires du cache selon les directives CacheDirLevels et CacheDirLength.

La directive CacheDirLevels définit le nombre de niveaux de sous-répertoires, et CacheDirLength le nombre de caractères composant le nom des sous-répertoires. Dans l'exemple donné plus haut, l'empreinte se trouvera à : /var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w.

Cette technique a pour but principal de réduire le nombre de sous-répertoires ou de fichiers contenus dans un répertoire particulier, car le fonctionnement de la plupart des systèmes de fichiers est ralenti quand ce nombre augmente. Avec la valeur "1" pour la directive CacheDirLength, il peut y avoir au plus 64 sous-répertoires à un niveau quelconque. Avec la valeur "2", il peut y en avoir 64 * 64, etc... A moins d'avoir une bonne raison pour ne pas le faire, l'utilisation de la valeur "1" pour la directive CacheDirLength est recommandée.

Le paramétrage de la directive CacheDirLevels dépend du nombre de fichiers que vous pensez stocker dans le cache. Avec une valeur de "2" comme dans l'exemple donné plus haut, 4096 sous-répertoires peuvent être créés au total. Avec 1 million de fichiers dans le cache, cela équivaut à environ 245 URLs mises en cache dans chaque répertoire.

Chaque URL nécessite au moins deux fichiers dans le cache. Ce sont en général un fichier ".header", qui contient des meta-informations à propos de l'URL, comme la date de son arrivée à expiration, et un fichier ".data" qui est la copie exacte du contenu à servir.

Dans le cas d'un contenu négocié via l'en-tête "Vary", un répertoire ".vary" sera créé pour l'URL en question. Ce répertoire contiendra de multiples fichiers ".data" correspondant aux différents contenus négociés.

Maintenance du cache sur disque

Le module mod_cache_disk n'effectue aucune régulation de l'espace disque utilisé par le cache, mais s'il s'arrête en douceur en cas d'erreur disque et se comporte alors comme si le cache n'avait jamais existé.

Par contre l'utilitaire htcacheclean fourni avec httpd vous permet de nettoyer le cache périodiquement. Déterminer la fréquence à laquelle lancer htcacheclean et la taille souhaitée pour le cache est une tâche relativement complexe et il vous faudra de nombreux essais et erreurs pour arriver à sélectionner des valeurs optimales.

htcacheclean opère selon deux modes. Il peut s'exécuter comme démon résident, ou être lancé périodiquement par cron. htcacheclean peut mettre une heure ou plus pour traiter de très grands caches (plusieurs dizaines de Gigaoctets) et si vous l'exécutez à partir de cron, il vous est conseillé de déterminer la durée typique d'un traitement, afin d'éviter d'exécuter plusieurs instances à la fois.

Il est aussi conseillé d'attribuer un niveau de priorité "nice" approprié à htcacheclean de façon à ce qu'il n'effectue pas trop d'accès disque pendant le fonctionnement du serveur.

Figure 1: Croissance typique du cache / séquence de nettoyage.

Comme mod_cache_disk ne tient pas compte de l'espace utilisé dans le cache, vous devez vous assurer que htcacheclean est configuré de façon à laisser suffisamment d'"espace de croissance" à la suite d'un nettoyage.

Cache en mémoire

En utilisant le module mod_cache_socache, mod_cache peut mettre en cache des données à partir de diverses implémentations aussi nommées "fournisseurs". Par exemple, en utilisant le module mod_socache_memcache, on peut spécifier que c'est memcached qui doit être utilisé comme mécanisme de stockage sous-jacent.

Typiquement, le module sera configuré comme suit :

CacheEnable socache /
CacheSocache memcache:memcd.example.com:11211

En outre, il est possible de spécifier plusieurs serveurs memcached en les ajoutant à la fin de la ligne CacheSocache memcache: et en les séparant par des virgules :

CacheEnable socache /
CacheSocache memcache:mem1.example.com:11211,mem2.example.com:11212

Divers autres fournisseurs mod_cache_socache utilisent aussi ce format. Par exemple :

CacheEnable socache /
CacheSocache shmcb:/path/to/datafile(512000)
CacheEnable socache /
CacheSocache dbm:/path/to/datafile

Mise en cache générale d'objets partagés à deux états de forme clé/valeur

Modules Apparentés Directives Apparentées
  • mod_authn_socache
  • mod_socache_dbm
  • mod_socache_dc
  • mod_socache_memcache
  • mod_socache_shmcb
  • mod_ssl
  • AuthnCacheSOCache
  • SSLSessionCache
  • SSLStaplingCache

Le serveur HTTP Apache fournit un cache d'objets partagés de bas niveau pour la mise en cache d'informations comme les sessions SSL ou les données d'authentification dans l'interface socache.

Pour chaque implémentation un module supplémentaire est fourni qui offre les services d'arrière-plan suivants :

mod_socache_dbm
Cache d'objets partagés basé sur DBM.
mod_socache_dc
Cache d'objets partagés basé sur Distcache.
mod_socache_memcache
Cache d'objets partagés basé sur Memcache.
mod_socache_shmcb
Cache d'objets partagés basé sur la mémoire partagée.

Mise en cache des données d'authentification

Modules Apparentés Directives Apparentées
  • mod_authn_socache
  • AuthnCacheSOCache

Le module mod_authn_socache permet la mise en cache des données issues d'une authentification, diminuant ainsi la charge des serveurs d'authentification d'arrière-plan.

Mise en cache des sessions SSL

Modules Apparentés Directives Apparentées
  • mod_ssl
  • SSLSessionCache
  • SSLStaplingCache

Le module mod_ssl utilise l'interface socache pour fournir un cache de session et un cache de base.

Mise en cache à base de fichiers spécialisés

Modules Apparentés Directives Apparentées
  • mod_file_cache
  • CacheFile
  • MMapFile

Sur les plateformes où le système de fichiers peut être lent, ou lorsque les descripteurs de fichiers sont gourmands en ressources, il est possible de précharger des fichiers en mémoire au démarrage du serveur.

Sur les systèmes où l'ouverture des fichiers est lente, il est possible d'ouvrir le fichier au démarrage du serveur et de mettre en cache le descripteur de fichier. Ces options peuvent vous aider sur les systèmes où l'accès aux fichiers statiques est lent.

Mise en cache des descripteurs de fichier

Le processus d'ouverture d'un fichier peut être en soi une source de ralentissement, en particulier sur les systèmes de fichiers sur le réseau. httpd permet d'éviter ce ralentissement en maintenant un cache des descripteurs de fichiers ouverts pour les fichiers souvent servis. Actuellement, httpd fournit une seule implémentation de mise en cache des descripteurs de fichiers.

CacheFile

La forme la plus basique de mise en cache que propose httpd est la mise en cache des descripteurs de fichiers fournie par le module mod_file_cache. Plutôt que de mettre en cache le contenu des fichiers, ce cache maintient une table des descripteurs de fichiers ouverts. Les fichiers devant faire l'objet d'une mise en cache de ce type sont spécifiés dans le fichier de configuration via la directive CacheFile.

La directive CacheFile informe httpd qu'il doit ouvrir le fichier lors de son démarrage et qu'il doit réutiliser le descripteur de fichier mis en cache pour tous les accès futurs à ce fichier.

CacheFile /usr/local/apache2/htdocs/index.html

Si vous désirez mettre en cache un grand nombre de fichiers de cette manière, vous devez vous assurer que le nombre maximal de fichiers ouverts pour votre système d'exploitation est défini à une valeur suffisante.

Bien que l'utilisation de la directive CacheFile n'entraîne pas de mise en cache du contenu du fichier proprement dit, elle implique que si le fichier est modifié pendant l'exécution du serveur, ces modifications ne seront pas prises en compte. Le fichier sera toujours servi dans l'état où il se trouvait au moment du démarrage du serveur.

Si le fichier est supprimé pendant l'exécution du serveur, ce dernier conservera le descripteur de fichier ouvert associé et servira le fichier dans l'état où il se trouvait au moment du démarrage du serveur. Cela signifie aussi que même si le fichier a été supprimé, et n'apparaît donc plus dans le système de fichiers, l'espace disque libéré ne sera disponible qu'une fois le serveur httpd arrêté et donc le descripteur de fichier fermé.

In-Memory Caching

Servir un contenu directement depuis la mémoire système est universellement reconnu comme la méthode la plus rapide. Lire des fichiers depuis un contrôleur de disque ou pire, depuis un réseau distant est plus lent de plusieurs ordres de grandeur. Les contrôleurs de disque réalisent en général des opérations mécaniques, et l'accès au réseau est limité par la bande passante dont vous disposez. Par contre, les temps d'accès à la mémoire sont de l'ordre de la nano-seconde.

Cependant la mémoire système n'est pas bon marché; à capacité égale, c'est de loin le type de stockage le plus coûteux et il est important de s'assurer qu'elle est utilisée efficacement. Le fait de mettre en cache des fichiers en mémoire diminue d'autant la quantité de mémoire système disponible. Comme nous le verrons plus loin, ce n'est pas un problème en soi dans le cas de la mise en cache par l'intermédiaire du système d'exploitation, mais si l'on utilise la mise en cache en mémoire propre à httpd, il faut prendre garde à ne pas allouer trop de mémoire au cache. Sinon le système sera contraint d'utiliser le swap, ce qui dégradera sensiblement les performances.

Mise en cache par l'intermédiaire du système d'exploitation

Dans la plupart des systèmes d'exploitation modernes, c'est le noyau qui gère directement la mise en cache en mémoire des données relatives aux fichiers. C'est une fonctionnalité puissante, et les systèmes d'exploitation s'en acquittent fort bien pour la plus grande partie. Considérons par exemple, dans le cas de Linux, la différence entre le temps nécessaire à la première lecture d'un fichier et le temps nécessaire à sa deuxième lecture;

colm@coroebus:~$ time cat testfile > /dev/null
real    0m0.065s
user    0m0.000s
sys     0m0.001s
colm@coroebus:~$ time cat testfile > /dev/null
real    0m0.003s
user    0m0.003s
sys     0m0.000s

Même pour ce petit fichier, il y a une grande différence entre les temps nécessaires pour lire le fichier. Ceci est du au fait que le noyau a mis en cache le contenu du fichier en mémoire.

Du fait de toujours pouvoir disposer de mémoire système, vous pouvez être assuré qu'il y aura de plus en plus de contenus de fichiers stockés dans ce cache. Ceci peut s'avérer une méthode de mise en cache en mémoire très efficace, et ne nécessite aucune configuration supplémentaire de httpd.

De plus, comme le système d'exploitation sait si des fichiers ont été supprimés ou modifiés, il peut effacer automatiquement des contenus de fichiers du cache lorsque cela s'avère nécessaire. Ceci constitue un gros avantage par rapport à la mise en cache en mémoire de httpd qui n'a aucune possibilité de savoir si un fichier a été modifié.

En dépit des performances et des avantages de la mise en cache automatique par le système d'exploitation, la mise en cache en mémoire peut être effectuée plus efficacement par httpd dans certaines circonstances.

Mise en cache à l'aide de la directive MMapFile

La directive MMapFile fournie par le module mod_file_cache vous permet de demander à httpd de charger un contenu de fichier statique en mémoire lors de son démarrage (à l'aide de l'appel système mmap). httpd utilisera le contenu chargé en mémoire pour satisfaire ultérieurement toutes les demandes d'accès à ce fichier.

MMapFile /usr/local/apache2/htdocs/index.html

Comme dans le cas de la directive CacheFile, toute modification du fichier ne sera plus prise en compte par httpd une fois ce dernier démarré.

La directive MMapFile ne gardant pas la trace de la quantité de mémoire qu'elle alloue, vous devez prendre garde de ne pas en abuser. Chaque processus enfant de httpd utilisant sa propre réplique de la mémoire allouée, il est donc d'une importance critique de s'assurer que les fichiers chargés ne sont pas d'une taille trop importante afin d'épargner au système l'utilisation du swap.

Considérations sur la sécurité

Autorisation et contrôle d'accès

Utiliser mod_cache revient sensiblement à la même chose qu'avoir un mandataire inverse intégré (reverse-proxy). Les requêtes seront servies par le module de mise en cache sauf si ce dernier détermine qu'un processus d'arrière-plan doit être appelé. La mise en cache de ressources locales modifie considérablement le modèle de sécurité de httpd.

Comme le parcours de la hiérarchie d'un système de fichiers pour examiner le contenu d'éventuels fichiers .htaccess serait une opération très coûteuse en ressources, annulant partiellement de ce fait l'intérêt de la mise en cache (accélérer le traitement des requêtes), mod_cache ne se préoccupe pas de savoir s'il a l'autorisation de servir une entité mise en cache. En d'autres termes, si mod_cache a mis en cache un certain contenu, ce dernier sera servi à partir du cache tant qu'il ne sera pas arrivé à expiration.

Si par exemple, votre configuration autorise l'accès à une ressource en fonction de l'adresse IP, vous devez vous assurer que ce contenu n'est pas mis en cache. Ceci est possible en utilisant la directive CacheDisable, ou le module mod_expires. Livré à lui-même, mod_cache - pratiquement comme un mandataire inverse - mettrait en cache le contenu lors de son service, et le servirait ensuite à tout client, vers n'importe quelle adresse IP.

Lorsque la directive CacheQuickHandler est définie à Off, toutes les phases du traitement de la requête sont exécutées et le modèle de sécurité reste le même.

Piratages locaux

Etant donné que les requêtes des utilisateurs finaux peuvent être servies depuis le cache, ce dernier est une cible potentielle pour ceux qui veulent défigurer un contenu ou interférer avec lui. Il est important de garder à l'esprit que l'utilisateur sous lequel tourne httpd doit toujours avoir l'accès en écriture dans le cache. Ceci est en contraste total avec la recommandation usuelle d'interdire à l'utilisateur sous lequel tourne Apache l'accès en écriture à tout contenu.

Si l'utilisateur sous lequel tourne Apache est compromis, par exemple à cause d'une faille de sécurité dans un processus CGI, il est possible que le cache fasse l'objet d'une attaque. Il est relativement aisé d'insérer ou de modifier une entité dans le cache en utilisant le module mod_cache_disk.

Cela représente un risque relativement élévé par rapport aux autres types d'attaques qu'il est possible de mener sous l'utilisateur apache. Si vous utilisez mod_cache_disk, vous devez garder ceci à l'esprit : effectuez toujours les mises à jour de httpdquand des correctifs de sécurité sont annoncés et exécutez les processus CGI sous un utilisateur autre qu'apache en utilisant suEXEC dans la mesure du possible.

Empoisonnement du cache (Cache Poisoning)

Si vous utilisez httpd comme serveur mandataire avec mise en cache, vous vous exposez aussi à un éventuel "Empoisonnement du cache" (Cache poisoning). L'empoisonnement du cache est un terme général pour désigner les attaques au cours desquelles l'attaquant fait en sorte que le serveur mandataire renvoie à un contenu incorrect (et souvent indésirable) suite à en provenance du serveur d'arrière-plan.

Par exemple, si les serveur DNS qu'utilise votre système où tourne httpd sont vulnérables à l'empoisonnement du cache des DNS, un attaquant pourra contrôler vers où httpd se connecte lorsqu'il demande un contenu depuis le serveur d'origine. Un autre exemple est constitué par les attaques ainsi nommées "Dissimulation de requêtes HTTP" (HTTP request-smuggling).

Ce document n'est pas le bon endroit pour une discussion approfondie à propos de la Dissimulation de requêtes HTTP (utilisez plutôt votre moteur de recherche favori); il est cependant important de savoir qu'il est possible d'élaborer une série de requêtes, et d'exploiter une vulnérabilité d'un serveur web d'origine de telle façon que l'attaquant puisse contrôler entièrement le contenu renvoyé par le mandataire.

Déni de Service / Cachebusting

Le mécanisme utilisé via l'en-tête Vary permet de mettre en cache simultanément plusieurs variantes d'une ressource avec la même URL. Le cache sélectionne la variante correcte à envoyer au client en fonction des valeurs d'en-tête fournies par ce dernier. Ce mécanisme peut devenir un problème lorsqu'on tente d'appliquer le mécanisme des variantes à un en-tête connu pour pouvoir posséder un grand nombre de valeurs possibles en utilisation normal, comme par exemple l'en-tête User-Agent. En fonction de la popularité du site web, des milliers ou même des millions d'entrées de cache dupliquées peuvent être créées pour la même URL, submergeant les autres entrées du cache.

Dans d'autres cas, il peut être nécessaire de modifier l'URL d'une ressource particulière à chaque requête, en général en lui ajoutant une chaîne "cachebuster". Si ce contenu est déclaré comme pouvant être mis en cache par un serveur avec une durée de fraîcheur significative, ces entrées peuvent submerger les entrées légitimes du cache. Alors que mod_cache fournit une directive CacheIgnoreURLSessionIdentifiers, cette dernière doit être utilisée avec prudence pour s'assurer que les caches du navigateur ou du mandataire le plus proche (downstream proxy) ne sont pas victimes du même problème de Déni de service.


Configuration à l'échelle du serveur - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Configuration à l'échelle du serveur

Ce document explique le fonctionnement de certaines directives du serveur de base qui sont utilisées pour configurer les opérations élémentaires du serveur.

Identification du serveur

Modules Apparentés Directives Apparentées
  • ServerName
  • ServerAdmin
  • ServerSignature
  • ServerTokens
  • UseCanonicalName
  • UseCanonicalPhysicalPort

Les directives ServerAdmin et ServerTokens contrôlent la nature des informations à propos du serveur qui seront affichées dans les documents générés par le serveur comme les messages d'erreur. La directive ServerTokens définit la valeur du champ d'en-tête de la réponse du serveur HTTP.

Le serveur utilise les directives ServerName, UseCanonicalName et UseCanonicalPhysicalPort pour déterminer la manière de construire des URLs vers ses propres ressources. Par exemple, quand un client émet une requête vers un répertoire, mais n'ajoute pas le slash final au nom du répertoire, httpd doit rediriger le client vers le nom complet incluant le slash final afin que le client puisse résoudre correctement les références relatives présentes dans le document.

Localisation des fichiers

Modules Apparentés Directives Apparentées
  • CoreDumpDirectory
  • DocumentRoot
  • ErrorLog
  • Mutex
  • PidFile
  • ScoreBoardFile
  • ServerRoot

Ces directives contrôlent la localisation des différents fichiers nécessaires au bon fonctionnement de httpd. Quand le chemin utilisé ne commence pas par un slash (/), la localisation des fichiers est relative à la valeur de la directive ServerRoot. Soyez prudent avec la localisation de fichiers dans des répertoires où les utilisateurs non root ont les droits en écriture. Voir la documention sur les Conseils à propos de la sécurité pour plus de détails.

Limitation de l'utilisation des ressources

Modules Apparentés Directives Apparentées
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldsize
  • LimitRequestLine
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • ThreadStackSize

Les directives LimitRequest* permettent de limiter la quantité de ressources consommées par httpd pour le traitement des requêtes des clients. Cette limitation permet de minimiser les effets de certains types d'attaques par déni de service.

Les directives RLimit* permettent de limiter la quantité de ressources utilisable par les processus initiés (forked) par les processus enfants httpd. Elles permettent en particulier de contrôler les ressources utilisées par les scripts CGI et les commandes exec des "Inclusions côté serveur" (Server Side Includes ou SSI).

La directive ThreadStackSize permet sur certaines plates-formes de contrôler la taille de la pile.

Choix d'implémentation

Modules Apparentés Directives Apparentées
  • Mutex

La directive Mutex permet de modifier l'implémentation sous-jacente des mutex, afin de résoudre les problèmes de fonctionnement ou de performance dus au choix par défaut d'APR.


Fichiers journaux - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Fichiers journaux

Pour véritablement gérer un serveur web, il est nécessaire de disposer d'un retour d'informations à propos de l'activité et des performances du serveur, ainsi que de tout problème qui pourrait survenir. Le serveur HTTP Apache propose des fonctionnalités de journalisation souples et très complètes. Ce document décrit comment configurer ces fonctionnalités de journalisation et interpréter le contenu des journaux.

Vue d'ensemble

Modules Apparentés Directives Apparentées
  • mod_log_config
  • mod_log_forensic
  • mod_logio
  • mod_cgi

Le serveur HTTP Apache fournit toute une variété de mécanismes différents pour la journalisation de tout ce qui peut se passer au sein de votre serveur, depuis la requête initiale, en passant par le processus de mise en correspondance des URLs, et jusqu'à la fermeture de la connexion, y compris toute erreur pouvant survenir au cours du traitement. De plus, certains modules tiers fournissent des fonctionnalités de journalisation ou insèrent des entrées dans les fichiers journaux existants, et les applications comme les programmes CGI, les scripts PHP ou autres gestionnaires peuvent envoyer des messages vers le journal des erreurs du serveur.

Ce document décrit le fonctionnement des modules de journalisation fournis en standard avec le serveur httpd.

Avertissement à propos de la sécurité

Tout utilisateur qui a les droits en écriture sur le répertoire dans lequel Apache httpd écrit ses journaux pourra quasi certainement avoir accès à l'uid sous lequel le serveur est démarré, en l'occurrence habituellement root. N'accordez PAS aux utilisateurs l'accès en écriture au répertoire dans lequel les journaux sont stockés sans savoir exactement quelles en seraient les conséquences ; voir le document conseils sur la sécurité pour plus de détails.

En outre, les journaux peuvent contenir des informations fournies directement par un client, sans caractères d'échappement. Des clients mal intentionnés peuvent donc insérer des caractères de contrôle dans les journaux, et il convient par conséquent d'être très prudent lors de la manipulation des journaux bruts.

Journal des erreurs

Modules Apparentés Directives Apparentées
  • core
  • ErrorLog
  • LogLevel

Le journal des erreurs du serveur, dont le nom et la localisation sont définis par la directive ErrorLog, est le journal le plus important. C'est dans celui-ci que le démon Apache httpd va envoyer les informations de diagnostic et enregistrer toutes les erreurs qui surviennent lors du traitement des requêtes. Lorsqu'un problème survient au démarrage du serveur ou pendant son fonctionnement, la première chose à faire est de regarder dans ce journal, car il vous renseignera souvent sur le problème rencontré et la manière d'y remédier.

Le journal des erreurs est habituellement enregistré dans un fichier (en général error_log sur les systèmes de type Unix et error.log sur Windows et OS/2). Sur les systèmes de type Unix, le serveur peut aussi enregistrer ses erreurs dans syslog ou les rediriger vers un programme par l'intermédiaire d'un tube de communication (pipe).

Le format par défaut du journal des erreurs est descriptif et de forme relativement libre. Certaines informations apparaissent cependant dans la plupart des entrées du journal. Voici un message typique à titre d'exemple :

[Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] client denied by server configuration: /export/home/live/ap/htdocs/test

Le premier champ de l'entrée du journal est la date et l'heure du message. Le second champ indique la sévérité de l'erreur rapportée. La directive LogLevel permet de restreindre le type des erreurs qui doivent être enregistrées dans le journal des erreurs en définissant leur niveau de sévérité. Le troisième champ contient l'adresse IP du client qui a généré l'erreur. Vient ensuite le message proprement dit, qui indique dans ce cas que le serveur a été configuré pour interdire l'accès au client. Le serveur indique le chemin système du document requis (et non son chemin web).

Une grande variété de messages différents peuvent apparaître dans le journal des erreurs. La plupart d'entre eux sont similaires à l'exemple ci-dessus. Le journal des erreurs peut aussi contenir des informations de débogage en provenance de scripts CGI. Toute information qu'un script CGI écrit sur la sortie d'erreurs standard stderr sera recopiée telle quelle dans le journal des erreurs.

La directive ErrorLogFormat vous permet de personnaliser le format du journal des erreurs, et de définir les informations à journaliser. Si mod_unique_id est présent, vous pouvez utiliser le drapeau %L à la fois dans le journal des erreurs et dans le journal des accès, ce qui aura pour effet de générer un identifiant d'entrée qui vous permettra de corréler les entrées du journal des erreurs avec celles du journal des accès.

Pendant la phase de test, il est souvent utile de visualiser en continu le journal des erreurs afin de détecter tout problème éventuel. Sur les systèmes de type Unix, ceci s'effectue à l'aide de la commande :

tail -f error_log

Journalisation par module

La directive LogLevel permet de spécifier un niveau de sévérité de journalisation pour chaque module. Vous pouvez ainsi résoudre un problème propre à un module particulier en augmentant son volume de journalisation sans augmenter ce volume pour les autres modules. Ceci est particulièrement utile lorsque vous voulez obtenir des détails sur le fonctionnement de modules comme mod_proxy ou mod_rewrite.

Pour ce faire, vous devez spécifier le nom du module dans votre directive LogLevel :

LogLevel info rewrite:trace5

Dans cet exemple, le niveau de journalisation général est défini à info, et à trace5 pour mod_rewrite.

Cette directive remplace les directives de journalisation par module des versions précédentes du serveur, comme RewriteLog.

Journal des accès

Modules Apparentés Directives Apparentées
  • mod_log_config
  • mod_setenvif
  • CustomLog
  • LogFormat
  • SetEnvIf

Le journal des accès au serveur enregistre toutes les requêtes que traite ce dernier. La localisation et le contenu du journal des accès sont définis par la directive CustomLog. La directive LogFormat permet de simplifier la sélection du contenu du journal. Cette section décrit comment configurer le serveur pour l'enregistrement des informations dans le journal des accès.

Bien évidemment, le stockage d'informations dans le journal des accès n'est que le point de départ de la gestion de la journalisation. L'étape suivante consiste à analyser ces informations de façon à pouvoir en extraire des statistiques utiles. L'analyse de journaux en général est en dehors du sujet de ce document et ne fait pas vraiment partie intégrante du travail du serveur web lui-même. Pour plus d'informations à propos de ce sujet et des applications dédiées à l'analyse de journaux, vous pouvez vous référer à Open Directory.

Différentes versions du démon Apache httpd utilisaient d'autres modules et directives pour contrôler la journalisation des accès, à l'instar de mod_log_referer, mod_log_agent, et de la directive TransferLog. La directive CustomLog rassemble désormais les fonctionnalités de toutes les anciennes directives.

Le format du journal des accès est hautement configurable. Il est défini à l'aide d'une chaîne de format qui ressemble sensiblement à la chaîne de format de style langage C de printf(1). Vous trouverez quelques exemples dans les sections suivantes. Pour une liste exhaustive de ce que peut contenir une chaîne de format, vous pouvez vous référer au chapitre chaînes de format de la documentation du module mod_log_config.

Format habituel du journal

Voici une configuration typique pour le journal des accès :

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common

Ici est définie l'identité common qui est ensuite associée à une chaîne de format de journalisation particulière. La chaîne de format est constituée de directives débutant par le caractère %, chacune d'entre elles indiquant au serveur d'enregistrer un élément particulier d'information. Des caractères littéraux peuvent aussi être insérés dans la chaîne de format ; il seront copiés tels quels dans le flux de sortie destiné à la journalisation. Les guillemets (") doivent être échappées en les faisant précéder d'un anti-slash (\) afin qu'elles ne soient pas interprétées comme la fin de la chaîne de format. La chaîne de format peut aussi contenir les caractères de contrôle spéciaux "\n" et "\t" pour insérer respectivement un passage à la ligne et une tabulation.

La directive CustomLog définit un nouveau fichier journal en l'associant à l'identité précédemment définie. Le chemin du nom de fichier associé au journal des accès est relatif au chemin défini par la directive ServerRoot, sauf s'il débute par un slash.

La configuration ci-dessus va enregistrer les entrées de journalisation selon un format connu sous le nom de Common Log Format (CLF) pour "Format de journalisation standard". Ce format standard peut être produit par de nombreux serveurs web différents et lu par de nombreux programmes d'analyse de journaux. Les entrées de fichier journal générées selon le format CLF ressemblent à ceci :

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326

Chaque partie de cette entrée de journal est décrite dans ce qui suit.

127.0.0.1 (%h)
Il s'agit de l'adresse IP du client (l'hôte distant) qui a envoyé la requête au serveur. Si la directive HostnameLookups est positionnée à On, le serveur va essayer de déterminer le nom de l'hôte et de l'enregistrer à la place de l'adresse IP. Cette configuration n'est cependant pas recommandée car elle peut ralentir le serveur de manière significative. Il est par conséquent préférable d'utiliser un processeur d'analyse de journaux a posteriori tel que logresolve pour déterminer les noms d'hôte. L'adresse IP indiquée ici n'est pas nécessairement l'adresse IP de la machine devant laquelle se trouve l'utilisateur. Si un serveur mandataire s'intercale entre le serveur et l'utilisateur, l'adresse indiquée sera celle du mandataire et non celle de la machine à l'origine de la requête.
- (%l)
Le "trait d'union" indique que la portion d'information correspondante n'est pas disponible. Dans le cas présent, l'information non disponible est l'identité (RFC 1413) du client telle que déterminée par identd sur la machine cliente. Cette information est très peu fiable et ne devrait jamais être utilisée, sauf dans le cas de réseaux internes étroitement contrôlés. Le démon httpd ne cherchera d'ailleurs à obtenir cette information que si la directive IdentityCheck est positionnée à On.
frank (%u)
Il s'agit de l'identifiant utilisateur de la personne qui a demandé le document, issu d'une authentification HTTP. Ce même identifiant est en général fourni aux scripts CGI par l'intermédiaire de la valeur de la variable d'environnement REMOTE_USER. Si le statut de la requête (voir plus loin) est 401, cette identifiant n'est pas fiable car l'utilisateur n'est pas encore authentifié. Si le document n'est pas protégé par mot de passe, cette partie d'information sera représentée par "-", comme la partie précédente.
[10/Oct/2000:13:55:36 -0700] (%t)
L'heure à laquelle la requête a été reçue. Le format est le suivant :

[jour/mois/année:heure:minutes:secondes zone]
jour = 2*chiffre
mois = 3*lettre
année = 4*chiffre
heure = 2*chiffre
minutes = 2*chiffre
secondes = 2*chiffre
zone = (`+' | `-') 4*chiffre

Il est possible de modifier le format d'affichage de l'heure en spécifiant %{format}t dans la chaîne de format du journal, où format est une chaîne de format de la forme de celle de la fonction strftime(3) de la bibliothèque C standard, ou choisie parmi les formats spéciaux supportés. Pour plus de détails, reportez-vous aux. chaînes de format de mod_log_config.
"GET /apache_pb.gif HTTP/1.0" (\"%r\")
La ligne de la requête du client est placée entre guillemets. Elle contient de nombreuses informations utiles. Tout d'abord, la méthode utilisée par le client est GET. Ensuite, le client a demandé la ressource /apache_pb.gif, et enfin, le client a utilisé le protocole HTTP/1.0. Il est aussi possible d'enregistrer séparément une ou plusieurs parties de la requête. Par exemple, la chaîne de format "%m %U %q %H" va enregistrer la méthode, le chemin, la chaîne de la requête et le protocole, ce qui donnera le même résultat que "%r".
200 (%>s)
C'est le code de statut que le serveur retourne au client. Cette information est très importante car elle indique si la requête a fait l'objet d'une réponse positive (codes commençant par 2), une redirection (codes commençant par 3), une erreur due au client (codes commençant par 4), ou une erreur due au serveur (codes commençant par 5). Vous trouverez la liste complète des codes de statut possibles dans la specification HTTP (RFC2616 section 10).
2326 (%b)
La dernière partie indique la taille de l'objet retourné au client, en-têtes non compris. Si aucun contenu n'a été retourné au client, cette partie contiendra "-". Pour indiquer l'absence de contenu par "0", utilisez %B au lieu de %b.

Combined Log Format (Format de journalisation combiné)

Une autre chaîne de format couramment utilisée est le "Combined Log Format" (Format de journalisation combiné). Il s'utilise comme suit :

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined
CustomLog log/access_log combined

Ce format est identique au Common Log Format, avec deux champs supplémentaires. Chacun de ces deux champs utilise la directive commençant par le caractère "%" %{header}i, où header peut être n'importe quel en-tête de requête HTTP. Avec ce format, le journal des accès se présentera comme suit :

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.example.com/start.html" "Mozilla/4.08 [en] (Win98; I ;Nav)"

Les champs supplémentaires sont :

"http://www.example.com/start.html" (\"%{Referer}i\")
L'en-tête "Referer" (sic) de la requête HTTP. Il indique le site depuis lequel le client prétend avoir lancé sa requête. (Ce doit être la page qui contient un lien vers /apache_pb.gif ou inclut ce dernier fichier).
"Mozilla/4.08 [en] (Win98; I ;Nav)" (\"%{User-agent}i\")
L'en-tête User-Agent de la requête HTTP. C'est une information d'identification que le navigateur du client envoie à propos de lui-même.

Journaux d'accès multiples

Plusieurs journaux d'accès peuvent être créés en spécifiant tout simplement plusieurs directives CustomLog dans le fichier de configuration. Par exemple, les directives suivantes vont créer trois journaux d'accès. Le premier contiendra les informations de base CLF, le second les informations du Referer, et le troisième les informations sur le navigateur. Les deux dernières directives CustomLog montrent comment simuler les effets des directives ReferLog et AgentLog.

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
CustomLog logs/referer_log "%{Referer}i -> %U"
CustomLog logs/agent_log "%{User-agent}i"

Cet exemple montre aussi qu'il n'est pas obligatoire d'associer une chaîne de format à un alias au moyen de la directive LogFormat. Elle peut être définie directement dans la ligne de la directive CustomLog.

Journalisation conditionnelle

Il est parfois souhaitable d'exclure certaines entrées des journaux d'accès en fonction des caractéristiques de la requête du client. On peut aisément accomplir ceci à l'aide des variables d'environnement. Tout d'abord, une variable d'environnement doit être définie pour indiquer que la requête remplit certaines conditions. Pour ceci, on utilise en général la directive SetEnvIf, puis la clause env= de la directive CustomLog pour inclure ou exclure les requêtes pour lesquelles la variable d'environnement est définie. Quelques exemples :

# Marque les requêtes en provenance de l'interface loop-back
SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog
# Marque les requêtes pour le fichier robots.txt
SetEnvIf Request_URI "^/robots\.txt$" dontlog
# Journalise toutes les autres requêtes
CustomLog logs/access_log common env=!dontlog

Autre exemple, imaginons l'enregistrement des requêtes en provenance d'utilisateurs de langue anglaise dans un journal, et celles des autres utilisateurs dans un autre journal.

        SetEnvIf Accept-Language "en" english
        CustomLog logs/english_log common env=english
        CustomLog logs/non_english_log common env=!english

Dans le contexte d'une mise en cache, il peut être intéressant de connaître l'efficacité du cache. Pour y parvenir, on pourrait utiliser cette méthode simple :

SetEnv CACHE_MISS 1
LogFormat "%h %l %u %t "%r " %>s %b %{CACHE_MISS}e" common-cache
CustomLog logs/access_log common-cache

mod_cache va s'exécuter avant mod_env, et si son action est couronnée de succès, il délivrera le contenu sans faire appel à ce dernier. Si l'URL se trouve dans le cache, la valeur journalisée sera alors -, tandis que dans le cas contraire elle sera 1.

En plus de la syntaxe env=, la directive LogFormat supporte les valeurs de journalisation conditionnelles basées sur le code de la réponse HTTP :

LogFormat "%400,501{User-agent}i" browserlog
LogFormat "%!200,304,302{Referer}i" refererlog

Dans le premier exemple, le User-agent sera enregistré si le code d'état HTTP est 400 ou 501. Dans le cas contraire, c'est un caractère "-" qui sera enregistré à la place. Dans le second exemple, le Referer sera enregistré si le code d'état HTTP n'est pas 200, 204, ou 302 (remarquez le caractère "!" avant les codes d'état).

Bien que nous venions de montrer que la journalisation conditionnelle est souple et très puissante, cette méthode de contrôle du contenu des journaux n'est pas la seule. Les fichiers journaux sont plus utiles quand ils contiennent un enregistrement complet de l'activité du serveur, et il est souvent plus aisé de simplement traiter à posteriori les fichiers journaux pour supprimer les requêtes que vous ne voulez pas y voir apparaître.

Rotation des journaux

Même dans le cas d'un serveur modérément sollicité, la quantité d'informations stockées dans les fichiers journaux est très importante. Le fichier journal des accès grossit en général d'1 Mo ou plus toutes les 10000 requêtes. Il est par conséquent nécessaire d'effectuer périodiquement la rotation des journaux en déplaçant ou supprimant les fichiers correspondants. On ne peut pas le faire pendant que le serveur est en cours d'exécution, car Apache httpd va continuer à écrire dans l'ancien fichier journal aussi longtemps qu'il le maintiendra ouvert. C'est pourquoi le serveur doit être redémarré après le déplacement ou la suppression des fichiers journaux de façon à ce qu'il en ouvre de nouveaux.

Avec un redémarrage graceful, on peut faire en sorte que le serveur ouvre de nouveaux fichiers journaux sans perdre de connexions existantes ou en cours avec les clients. Cependant, pour que ceci soit possible, le serveur doit continuer à écrire dans les anciens fichiers journaux pendant qu'il termine le traitement des requêtes en cours. Il est donc nécessaire d'attendre un certain temps après le rédémarrage avant d'effectuer tout traitement sur les fichiers journaux. Voici un scénario typique dans lequel on effectue une simple rotation des journaux en compressant les anciens fichiers correspondants afin de gagner de l'espace disque :

mv access_log access_log.old
mv error_log error_log.old
apachectl graceful
sleep 600
gzip access_log.old error_log.old

La section suivante présente une autre méthode de rotation des journaux qui consiste à utiliser les journaux redirigés.

Journaux redirigés

Nous avons vu que le démon httpd écrivait les informations de journalisation des erreurs et des accès dans un fichier journal ; il peut aussi rediriger ces informations vers un autre processus par l'intermédiaire d'un tube de communication (pipe). Cette fonctionnalité améliore considérablement la souplesse de la journalisation, sans ajouter de code au serveur principal. Pour rediriger les informations de journalisation vers un tube de communication, remplacez simplement le nom de fichier journal par le caractère pipe "|", suivi du nom de l'exécutable qui va recueillir les entrées de journal sur son entrée standard. Le serveur va lancer le processus de redirection des journaux au moment du démarrage du serveur, et le relancera s'il cesse de fonctionner pendant l'exécution du serveur. (Nous dénommons cette technique "journalisation redirigée fiable" grâce à cette dernière fonctionnalité.)

Les processus de journalisation redirigée sont lancés par le processus httpd parent, et héritent de l'UID de ce dernier. Cela signifie que les programmes de journalisation dirigée s'exécutent généralement en tant que root. Il est donc très important que ces programmes soient simples et sécurisés.

Un des grands avantages de la journalisation redirigée est la possibilité d'effectuer la rotation des journaux sans avoir à redémarrer le serveur. Pour accomplir cette tâche, le serveur HTTP Apache fournit un programme simple appelé rotatelogs. Par exemple, pour une rotation des journaux toutes les 24 heures, ajoutez ces lignes :

CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common

Notez que l'ensemble de la commande qui sera appelée par le tube de communication a été placée entre guillemets. Bien que cet exemple concerne le journal des accès, la même technique peut être utilisée pour le journal des erreurs.

Comme la journalisation conditionnelle, la journalisation redirigée est un outil très puissant, mais si elle existe, il est préférable d'utiliser une solution plus simple comme le traitement à posteriori hors ligne.

Par défaut, le processus de redirection du journal est lancé sans invoquer un shell. Pour invoquer un shell, utilisez "|$" au lieu de "|" (en général avec /bin/sh -c) :

# Invocation de "rotatelogs" en utilisant un shell
CustomLog "|$/usr/local/apache/bin/rotatelogs   /var/log/access_log 86400" common

Il s'agissait du comportement par défaut sous Apache 2.2. Selon les spécificités du shell, ceci peut générer un processus shell supplémentaire pour toute la durée du programme de redirection du journal, et induire des problèmes de gestion de signaux au cours du redémarrage. La notation "||" est aussi supportée pour des raisons de compatibilité avec Apache 2.2 et est équivalente à "|".

Note à propos de la plateforme Windows

Notez que sous Windows, la mémoire allouée au bureau (desktop heap) peut devenir insuffisante si vous utilisez de nombreux processus vers lesquels sont redirigés des journaux via un pipe, et ceci particulièrement si httpd s'exécute en tant que service. La quantité de mémoire du bureau allouée à chaque service est spécifiée dans le troisième argument du paramètre SharedSection de la clé de registre HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\SessionManager\SubSystems\Windows. Modifiez cette valeur avec prudence ; les précautions d'usage s'imposent lorsqu'on modifie la base de registre, mais vous pouvez aussi saturer la mémoire du bureau si vous spécifiez une valeur trop élevée.

Hôtes virtuels

Lorsqu'un serveur possède plusieurs hôtes virtuels, il existe de nombreuses solutions pour gérer les fichiers journaux. Par exemple, on peut utiliser les journaux comme s'il s'agissait d'un serveur avec un seul hôte. Il suffit pour cela de placer les directives de journalisation en dehors des sections <VirtualHost> au niveau du serveur principal, ce qui a pour effet de journaliser toutes les requêtes dans le même journal des accès et des erreurs. Cette technique est cependant inappropriée pour recueillir des statistiques sur chaque hôte virtuel individuellement.

Si des directives CustomLog ou ErrorLog sont placées dans une section <VirtualHost>, toutes les requêtes ou erreurs pour cet hôte virtuel ne seront enregistrées que dans le fichier spécifié. Tout hôte virtuel qui ne possède pas de directives de journalisation verra ses requêtes enregistrées dans le journal du serveur principal. Cette technique est appropriée pour un petit nombre d'hôtes virtuels, mais si ce nombre est important, elle peut devenir compliquée à gérer. En outre, des problèmes de nombre de descripteurs de fichiers insuffisant peuvent rapidement apparaître.

Il existe un très bon compromis pour le journal des accès. En intégrant les informations à propos de l'hôte virtuel à la chaîne de format du journal, il est possible de journaliser tous les hôtes dans le même journal, puis de séparer ultérieurement le journal en plusieurs journaux individuels. Considérons par exemple les directives suivantes :

LogFormat "%v %l %u %t \"%r\" %>s %b" comonvhost
CustomLog logs/access_log comonvhost

Le champ %v sert à enregistrer le nom de l'hôte virtuel qui traite la requête. Un programme tel que split-logfile peut ensuite être utilisé pour générer "à froid" autant de journaux que d'hôtes virtuels.

Autres fichiers journaux

Modules Apparentés Directives Apparentées
  • mod_logio
  • mod_log_config
  • mod_log_forensic
  • mod_cgi
  • LogFormat
  • BufferedLogs
  • ForensicLog
  • PidFile
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength

Enregistrement du nombre réel d'octets envoyés et reçus

Le module mod_logio fournit deux champs LogFormat supplémentaires (%I et %O) qui permettent d'enregistrer le nombre réel d'octets reçus et envoyés sur le réseau.

Journalisation de style investigation judiciaire (forensic logging)

Le module mod_log_forensic permet la journalisation à des fins d'investigation judiciaire des requêtes des clients. La journalisation est effectuée avant et après le traitement de la requête, qui fait donc l'objet de deux entrées dans le journal. Le générateur de journaux d'investigation est très strict et ne permet aucune personnalisation. C'est un inestimable outil de débogage et de sécurité.

Fichier PID

Au démarrage, le démon httpd Apache enregistre l'identifiant du processus httpd parent dans le fichier logs/httpd.pid. Le nom de ce fichier peut être modifié à l'aide de la directive PidFile. Cet identifiant permet à l'administrateur de redémarrer et arrêter le démon en envoyant des signaux au processus parent ; sous Windows, vous devez utiliser l'option de ligne de commande -k. Pour plus de détails, consulter la page Arrêt et redémarrage.

Journal des scripts

Afin de faciliter le débogage, la directive ScriptLog vous permet d'enregistrer les entrées et sorties des scripts CGI. Elle ne doit être utilisée que pendant la phase de test, et en aucun cas sur un serveur en production. Vous trouverez plus d'informations dans la documentation du module mod_cgi.


Mise en correspondance des URLs avec le système de fichiers - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

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

Ce document explique comment le serveur HTTP Apache utilise l'URL contenue dans une requête pour déterminer le noeud du système de fichier à partir duquel le fichier devra être servi.

Modules et directives concernés

Modules Apparentés Directives Apparentées
  • mod_actions
  • mod_alias
  • mod_autoindex
  • mod_dir
  • mod_imagemap
  • mod_negotiation
  • mod_proxy
  • mod_rewrite
  • mod_speling
  • mod_userdir
  • mod_vhost_alias
  • Alias
  • AliasMatch
  • CheckSpelling
  • DirectoryIndex
  • DocumentRoot
  • ErrorDocument
  • Options
  • ProxyPass
  • ProxyPassReverse
  • ProxyPassReverseCookieDomain
  • ProxyPassReverseCookiePath
  • Redirect
  • RedirectMatch
  • RewriteCond
  • RewriteRule
  • ScriptAlias
  • ScriptAliasMatch
  • UserDir

Racine des documents (DocumentRoot)

La méthode par défaut de httpd pour déterminer quel fichier servir pour une requête donnée, consiste à extraire le chemin du fichier de la requête (la partie de l'URL qui suit le nom d'hôte et le port), puis de l'ajouter à la fin de la valeur de la directive DocumentRoot définie dans vos fichiers de configuration. Ainsi, les fichiers et répertoires situés en dessous de DocumentRoot constituent l'arborescence de base des documents qui seront visibles depuis le web.

Par exemple, si la directive DocumentRoot contient /var/www/html, une requête pour http://www.example.com/fish/guppies.html retournera le fichier /var/www/html/fish/guppies.html au client.

Si la requête concerne un répertoire (autrement dit un chemin se terminant par un slash /), le nom du fichier qui sera recherché et servi depuis ce répertoire est défini via la directive DirectoryIndex. Par exemple, supposons que DocumentRoot ait été définie comme précédemment, et que vous ayez défini DirectoryIndex comme suit :

DirectoryIndex index.html index.php

Si httpd reçoit alors une requête pour http://www.example.com/fish/, il tentera de servir le fichier /var/www/html/fish/index.html. Si ce fichier n'existe pas, il tentera de servir le fichier /var/www/html/fish/index.php.

Si aucun de ces fichiers existe, httpd tentera de générer et d'afficher un index du répertoire, à condition que mod_autoindex ait été chargé et configuré pour le permettre.

httpd supporte aussi les Hôtes virtuels, ce qui lui permet de traiter des requêtes pour plusieurs hôtes. Dans ce cas, un DocumentRoot différent peut être défini pour chaque hôte virtuel; les directives fournies par le module mod_vhost_alias peuvent aussi être utilisées afin de déterminer dynamiquement le noeud approprié du système de fichiers à partir duquel servir un contenu en fonction de l'adresse IP ou du nom d'hôte.

La directive DocumentRoot est définie dans le fichier de configuration de votre serveur principal (httpd.conf), mais peut aussi être redéfinie pour chaque Hôte virtuel supplémentaire que vous avez créé.

Fichiers situés en dehors de l'arborescence DocumentRoot

Il existe de nombreuses circonstances pour lesquelles il est nécessaire d'autoriser l'accès web à des portions du système de fichiers qui ne se trouvent pas dans l'arborescence DocumentRoot. httpd propose de nombreuses solutions pour réaliser cela. Sur les systèmes Unix, les liens symboliques permettent de rattacher d'autres portions du système de fichiers au DocumentRoot. Pour des raisons de sécurité, httpd ne suivra les liens symboliques que si les Options pour le répertoire concerné contiennent FollowSymLinks ou SymLinksIfOwnerMatch.

Une autre méthode consiste à utiliser la directive Alias pour rattacher toute portion du système de fichiers à l'arborescence du site web. Par exemple, avec

Alias "/docs" "/var/web"

l'URL http://www.example.com/docs/dir/file.html correspondra au fichier /var/web/dir/file.html. La directive ScriptAlias fonctionne de la même manière, excepté que tout contenu localisé dans le chemin cible sera traité comme un script CGI.

Pour les situations qui nécessitent plus de flexibilité, vous disposez des directives AliasMatch et ScriptAliasMatch qui permettent des substitutions et comparaisons puissantes basées sur les expressions rationnelles. Par exemple,

ScriptAliasMatch "^/~([a-zA-Z0-9]+)/cgi-bin/(.+)" "/home/$1/cgi-bin/$2"

fera correspondre une requête du style http://example.com/~user/cgi-bin/script.cgi au chemin /home/user/cgi-bin/script.cgi, et traitera le fichier résultant comme un script CGI.

Répertoires des utilisateurs

Sur les systèmes Unix, on peut traditionnellement faire référence au répertoire personnel d'un utilisateur particulier à l'aide de l'expression ~user/. Le module mod_userdir étend cette idée au web en autorisant l'accès aux fichiers situés dans les répertoires home des utilisateurs à l'aide d'URLs comme dans ce qui suit :

http://www.example.com/~user/file.html

Pour des raisons de sécurité, il est déconseillé de permettre un accès direct à un répertoire home d'utilisateur depuis le web. A cet effet, la directive UserDir spécifie un répertoire où sont situés les fichiers accessibles depuis le web dans le répertoire home de l'utilisateur. Avec la configuration par défaut Userdir public_html, l'URL ci-dessus correspondra à un fichier dont le chemin sera du style /home/user/public_html/file.html où /home/user/ est le répertoire home de l'utilisateur tel qu'il est défini dans /etc/passwd.

La directive Userdir met à votre disposition de nombreuses formes différentes pour les systèmes où /etc/passwd ne spécifie pas la localisation du répertoire home.

Certains jugent le symbole "~" (dont le code sur le web est souvent %7e) inapproprié et préfèrent utiliser une chaîne de caractères différente pour représenter les répertoires utilisateurs. mod_userdir ne supporte pas cette fonctionnalité. Cependant, si les répertoires home des utilisateurs sont structurés de manière rationnelle, il est possible d'utiliser la directive AliasMatch pour obtenir l'effet désiré. Par exemple, pour faire correspondre http://www.example.com/upages/user/file.html à /home/user/public_html/file.html, utilisez la directive AliasMatch suivante :

AliasMatch "^/upages/([a-zA-Z0-9]+)(/(.*))?$"   "/home/$1/public_html/$3"

Redirection d'URL

Les directives de configuration décrites dans les sections précédentes demandent à httpd d'extraire un contenu depuis un emplacement spécifique du système de fichiers et de la retourner au client. Il est cependant parfois souhaitable d'informer le client que le contenu demandé est localisé à une URL différente, et de demander au client d'élaborer une nouvelle requête avec la nouvelle URL. Ce processus se nomme redirection et est implémenté par la directive Redirect. Par exemple, si le contenu du répertoire /foo/ sous DocumentRoot est déplacé vers le nouveau répertoire /bar/, vous pouvez demander aux clients de le requérir à sa nouvelle localisation comme suit :

Redirect permanent "/foo/"   "http://www.example.com/bar/"

Ceci aura pour effet de rediriger tout chemin d'URL commençant par /foo/ vers le même chemin d'URL sur le serveur www.example.com en remplaçant /foo/ par /bar/. Vous pouvez rediriger les clients non seulement sur le serveur d'origine, mais aussi vers n'importe quel autre serveur.

httpd propose aussi la directive RedirectMatch pour traiter les problèmes de réécriture d'une plus grande complexité. Par exemple, afin de rediriger les requêtes pour la page d'accueil du site vers un site différent, mais laisser toutes les autres requêtes inchangées, utilisez la configuration suivante :

RedirectMatch permanent "^/$"    "http://www.example.com/startpage.html"

De même, pour rediriger temporairement toutes les pages d'un site vers une page particulière d'un autre site, utilisez ce qui suit :

RedirectMatch temp ".*"  "http://othersite.example.com/startpage.html"

Mandataire inverse (Reverse Proxy)

httpd vous permet aussi de rapatrier des documents distants dans l'espace des URL du serveur local. Cette technique est appelée mandataire inverse ou reverse proxying car le serveur web agit comme un serveur mandataire en rapatriant les documents depuis un serveur distant puis les renvoyant au client. Ceci diffère d'un service de mandataire usuel (direct) car, pour le client, les documents semblent appartenir au serveur mandataire inverse.

Dans l'exemple suivant, quand les clients demandent des documents situés dans le répertoire /foo/, le serveur rapatrie ces documents depuis le répertoire /bar/ sur internal.example.com et les renvoie au client comme s'ils appartenaient au serveur local.

ProxyPass "/foo/" "http://internal.example.com/bar/"
ProxyPassReverse "/foo/" "http://internal.example.com/bar/"
ProxyPassReverseCookieDomain internal.example.com public.example.com
ProxyPassReverseCookiePath "/foo/" "/bar/"

La directive ProxyPass configure le serveur pour rapatrier les documents appropriés, alors que la directive ProxyPassReverse réécrit les redirections provenant de internal.example.com de telle manière qu'elles ciblent le répertoire approprié sur le serveur local. De manière similaire, les directives ProxyPassReverseCookieDomain et ProxyPassReverseCookiePath réécrivent les cookies élaborés par le serveur d'arrière-plan.

Il est important de noter cependant, que les liens situés dans les documents ne seront pas réécrits. Ainsi, tout lien absolu sur internal.example.com fera décrocher le client du serveur mandataire et effectuer sa requête directement sur internal.example.com. Vous pouvez modifier ces liens (et d'utres contenus) situés dans la page au moment où elle est envoyée au client en utilisant le module mod_substitute.

Substitute "s/internal\.example\.com/www.example.com/i"

Le module mod_proxy_html rend possible une réécriture plus élaborée des liens en HTML et XHTML. Il permet de créer des listes d'URLs et de leurs réécritures, de façon à pouvoir gérer des scénarios de réécriture complexes.

Moteur de réécriture

Le moteur de réécriture mod_rewrite peut s'avérer utile lorsqu'une substitution plus puissante est nécessaire. Les directives fournies par ce module peuvent utiliser des caractéristiques de la requête comme le type de navigateur ou l'adresse IP source afin de décider depuis où servir le contenu. En outre, mod_rewrite peut utiliser des fichiers ou programmes de bases de données externes pour déterminer comment traiter une requête. Le moteur de réécriture peut effectuer les trois types de mise en correspondance discutés plus haut : redirections internes (aliases), redirections externes, et services mandataires. De nombreux exemples pratiques utilisant mod_rewrite sont discutés dans la documentation détaillée de mod_rewrite.

Fichier non trouvé (File Not Found)

Inévitablement, apparaîtront des URLs qui ne correspondront à aucun fichier du système de fichiers. Ceci peut arriver pour de nombreuses raisons. Il peut s'agir du déplacement de documents d'une localisation vers une autre. Dans ce cas, le mieux est d'utiliser la redirection d'URL pour informer les clients de la nouvelle localisation de la ressource. De cette façon, vous êtes sur que les anciens signets et liens continueront de fonctionner, même si la ressource est déplacée.

Une autre cause fréquente d'erreurs "File Not Found" est l'erreur de frappe accidentelle dans les URLs, soit directement dans le navigateur, soit dans les liens HTML. httpd propose le module mod_speling (sic) pour tenter de résoudre ce problème. Lorsque ce module est activé, il intercepte les erreurs "File Not Found" et recherche une ressource possédant un nom de fichier similaire. Si un tel fichier est trouvé, mod_speling va envoyer une redirection HTTP au client pour lui communiquer l'URL correcte. Si plusieurs fichiers proches sont trouvés, une liste des alternatives possibles sera présentée au client.

mod_speling possède une fonctionnalité particulièrement utile : il compare les noms de fichiers sans tenir compte de la casse. Ceci peut aider les systèmes où les utilisateurs ne connaissent pas la sensibilité des URLs à la casse et bien sûr les systèmes de fichiers unix. Mais l'utilisation de mod_speling pour toute autre chose que la correction occasionnelle d'URLs peut augmenter la charge du serveur, car chaque requête "incorrecte" entraîne une redirection d'URL et une nouvelle requête de la part du client.

mod_dir fournit la directive FallbackResource qui permet d'associer des URIs virtuels à une ressource réelle qui peut ainsi les servir. Cette directive remplace avantageusement mod_rewrite lors de l'implémentation d'un "contrôleur frontal".

Si toutes les tentatives pour localiser le contenu échouent, httpd retourne une page d'erreur avec le code de statut HTTP 404 (file not found). L'apparence de cette page est contrôlée à l'aide de la directive ErrorDocument et peut être personnalisée de manière très flexible comme discuté dans le document Réponses personnalisées aux erreurs.

Autres modules de mise en correspondance des URLs

Les autres modules disponibles pour la mise en correspondance des URLs sont :

  • mod_actions - Met une URL en correspondance avec un script CGI en fonction de la méthode de la requête, ou du type MIME de la ressource.
  • mod_dir - Permet une mise en correspondance basique d'un slash terminal dans un fichier index comme index.html.
  • mod_imagemap - Met en correspondance une requête avec une URL en fonction de la zone d'une image intégrée à un document HTML dans laquelle un utilisateur clique.
  • mod_negotiation - Sélectionne le document approprié en fonction de préférences du client telles que la langue ou la compression du contenu.


Support des objets dynamiques partagés (DSO) - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Support des objets dynamiques partagés (DSO)

La conception modulaire du serveur HTTP Apache permet à l'administrateur de choisir les fonctionnalités à inclure dans le serveur en sélectionnant un certain nombre de modules. Les modules seront compilés en tant qu'Objets Dynamiques Partagés (Dynamic Shared Objects ou DSOs) qui mènent une existence séparée du fichier binaire principal httpd. Les modules DSO peuvent être compilés en même temps que le serveur, ou compilés et ajoutés ultérieurement via l'Outil des Extensions à Apache (Apache Extension Tool ou apxs).

Les modules peuvent aussi être intégrés statiquement dans le binaire httpd lors de la compilation de ce dernier.

Ce document décrit l'utilisation des modules DSO ainsi que les dessous de leur fonctionnement.

Implémentation

Modules Apparentés Directives Apparentées
  • mod_so
  • LoadModule

Le support DSO pour le chargement de modules individuels d'Apache httpd est assuré par un module nommé mod_so qui doit être compilé statiquement dans le coeur d'Apache httpd. Il s'agit du seul module avec le module core à ne pas pouvoir être compilé en tant que module DSO lui-même. Pratiquement tous les autres modules d'Apache httpd distribués seront alors compilés en tant que modules DSO. Une fois compilé en tant que module DSO nommé mod_foo.so, un module peut être chargé en mémoire au démarrage ou redémarrage du serveur à l'aide de la directive LoadModule du module mod_so, placée dans votre fichier httpd.conf.

La compilation en mode DSO peut être désactivée pour certains modules via l'option --enable-mods-static du script configure, comme expliqué dans la Documentation sur l'installation.

Un utilitaire permet de simplifier la création de fichiers DSO pour les modules d'Apache httpd (particulièrement pour les modules tiers) ; il s'agit du programme nommé apxs (APache eXtenSion). On peut l'utiliser pour construire des modules de type DSO en dehors de l'arborescence des sources d'Apache httpd. L'idée est simple : à l'installation du serveur HTTP Apache, la procédure make install du script configure installe les fichiers d'en-têtes d'Apache httpd et positionne, pour la plateforme de compilation, les drapeaux du compilateur et de l'éditeur de liens à l'intérieur du programme apxs, qui sera utilisé pour la construction de fichiers DSO. Il est ainsi possible d'utiliser le programme apxs pour compiler ses sources de modules Apache httpd sans avoir besoin de l'arborescence des sources de la distribution d'Apache, et sans avoir à régler les drapeaux du compilateur et de l'éditeur de liens pour le support DSO.

Mode d'emploi succinct

Afin que vous puissiez vous faire une idée des fonctionnalités DSO du serveur HTTP Apache 2.x, en voici un résumé court et concis :

  1. Construire et installer un module Apache httpd faisant partie de la distribution, par exemple mod_foo.c, en tant que module DSO mod_foo.so :

    $ ./configure --prefix=/chemin/vers/installation --enable-foo
    $ make install

  2. Configure le serveur HTTP Apache avec tous les modules activés. Seul un jeu de modules de base sera chargé au démarrage du serveur. Vous pouvez modifier ce jeu de modules chargés au démarrage en activant ou désactivant les directives LoadModule correspondantes dans le fichier httpd.conf.

    $ ./configure --enable-mods-shared=all
    $ make install

    L'argument most de l'option --enable-modules indique que tous les modules non-expérimentaux ou qui ne sont pas là à titre d'exemple seront compilés.

  3. Certains modules ne sont utilisés que par les développeurs et ne seront pas compilés. Si vous voulez les utiliser, spécifiez l'option all. Pour compiler tous les modules disponibles, y compris les modules de développeurs, spécifiez l'option reallyall. En outre, la directive LoadModule peut être activée pour tous les modules compilés via l'option du script configure --enable-load-all-modules.

    $ ./configure --enable-mods-shared=reallyall --enable-load-all-modules
    $ make install

  4. Construire et installer un module Apache httpd tiers, par exemple mod_foo.c, en tant que module DSO mod_foo.so en dehors de l'arborescence des sources d'Apache httpd à l'aide du programme apxs :

    $ cd /chemin/vers/module_tiers
    $ apxs -cia mod_foo.c

Dans tous les cas, une fois le module partagé compilé, vous devez ajouter une directive LoadModule dans le fichier httpd.conf pour qu'Apache httpd active le module.

Voir la documentation sur apxs pour plus de détails.

Les dessous du fonctionnement des DSO

Les clônes modernes d'UNIX proposent un mécanisme appelé édition de liens et chargement dynamiques d' Objets Dynamiques Partagés (DSO), qui permet de construire un morceau de programme dans un format spécial pour le rendre chargeable à l'exécution dans l'espace d'adressage d'un programme exécutable.

Ce chargement peut s'effectuer de deux manières : automatiquement par un programme système appelé ld.so quand un programme exécutable est démarré, ou manuellement à partir du programme en cours d'exécution via sa propre interface système vers le chargeur Unix à l'aide des appels système dlopen()/dlsym().

Dans la première méthode, les DSO sont en général appelés bibliothèques partagées ou encore bibliothèques DSO, et possèdent des noms du style libfoo.so ou libfoo.so.1.2. Ils résident dans un répertoire système (en général /usr/lib) et le lien avec le programme exécutable est établi à la compilation en ajoutant -lfoo à la commande de l'éditeur de liens. Les références à la bibliothèque sont ainsi codées en dur dans le fichier du programme exécutable de façon à ce qu'au démarrage du programme, le chargeur Unix soit capable de localiser libfoo.so dans /usr/lib, dans des chemins codés en dur à l'aide d'options de l'éditeur de liens comme -R ou dans des chemins définis par la variable d'environnement LD_LIBRARY_PATH. Le chargeur peut dès lors résoudre tous les symboles (jusque là non encore résolus) du DSO dans le programme exécutable.

Les symboles du programme exécutable ne sont en général pas référencés par le DSO (car c'est une bibliothèque de code à usage général et réutilisable), et ainsi aucune résolution supplémentaire n'est nécessaire. De son côté, le programme exécutable ne doit accomplir aucune action particulière pour utiliser les symboles du DSO car toutes les résolutions sont effectuées par le chargeur Unix. En fait, le code permettant d'invoquer ld.so fait partie du code de démarrage pour l'exécution qui est lié dans tout programme exécutable non statiquement lié. L'avantage du chargement dynamique du code d'une bibliothèque partagée est évident : le code de la bibliothèque ne doit être stocké qu'une seule fois dans une bibliothèque système telle que libc.so, ce qui permet d'économiser de l'espace disque pour les autres programmes.

Dans la seconde méthode, les DSO sont en général appelés objets partagés ou fichiers DSO, et peuvent être nommés avec l'extension de son choix (bien que le nom conseillé soit du style foo.so). Ces fichiers résident en général dans un répertoire spécifique à un programme, et aucun lien n'est automatiquement établi avec le programme exécutable dans lequel ils sont utilisés. Le programme exécutable charge manuellement le DSO à l'exécution dans son espace d'adressage à l'aide de l'appel système dlopen(). A ce moment, aucune résolution de symboles du DSO n'est effectuée pour le programme exécutable. Par contre le chargeur Unix résoud automatiquement tout symbole du DSO (non encore résolu) faisant partie de l'ensemble de symboles exporté par le programme exécutable et ses bibliothèques DSO déjà chargées (et en particulier tous les symboles de la bibliothèque à tout faire libc.so). De cette façon, le DSO prend connaissance de l'ensemble de symboles du programme exécutable comme s'il avait été lié statiquement avec lui auparavant.

Finalement, pour tirer profit de l'API des DSO, le programme exécutable doit résoudre certains symboles du DSO à l'aide de l'appel système dlsym() pour une utilisation ultérieure dans les tables de distribution, etc... En d'autres termes, le programme exécutable doit résoudre manuellement tous les symboles dont il a besoin pour pouvoir les utiliser. Avantage d'un tel mécanisme : les modules optionnels du programme n'ont pas besoin d'être chargés (et ne gaspillent donc pas de ressources mémoire) tant qu'il ne sont pas nécessaires au programme en question. Si nécessaire, ces modules peuvent être chargés dynamiquement afin d'étendre les fonctionnalités de base du programme.

Bien que ce mécanisme DSO paraisse évident, il comporte au moins une étape difficile : la résolution des symboles depuis le programme exécutable pour le DSO lorsqu'on utilise un DSO pour étendre les fonctionnalités d'un programme (la seconde méthode). Pourquoi ? Parce que la "résolution inverse" des symboles DSO à partir du jeu de symboles du programme exécutable dépend de la conception de la bibliothèque (la bibliothèque n'a aucune information sur le programme qui l'utilise) et n'est ni standardisée ni disponible sur toutes les plateformes. En pratique, les symboles globaux du programme exécutable ne sont en général pas réexportés et donc indisponibles pour l'utilisation dans un DSO. Trouver une méthode pour forcer l'éditeur de liens à exporter tous les symboles globaux est le principal problème que l'on doit résoudre lorsqu'on utilise un DSO pour étendre les fonctionnalités d'un programme au moment de son exécution.

L'approche des bibliothèques partagées est la plus courante, parce que c'est dans cette optique que le mécanisme DSO a été conçu ; c'est cette approche qui est ainsi utilisée par pratiquement tous les types de bibliothèques que fournit le système d'exploitation.

Avantages et inconvénients

Les fonctionnalités ci-dessus basées sur les DSO présentent les avantages suivants :

  • Le paquetage du serveur est plus flexible à l'exécution car le processus serveur peut être assemblé à l'exécution via la directive LoadModule du fichier de configuration httpd.conf plutôt que par des options du script configure à la compilation. Par exemple, on peut ainsi exécuter différentes instances du serveur (standard et version SSL, version minimale et version dynamique [mod_perl, mod_php], etc...) à partir d'une seule installation d'Apache httpd.
  • Le paquetage du serveur peut être facilement étendu avec des modules tiers, même après l'installation. Ceci présente un gros avantage pour les mainteneurs de paquetages destinés aux distributions, car ils peuvent créer un paquetage Apache httpd de base, et des paquetages additionnels contenant des extensions telles que PHP, mod_perl, mod_fastcgi, etc...
  • Une facilité de prototypage des modules Apache httpd, car la paire DSO/apxs vous permet d'une part de travailler en dehors de l'arborescence des sources d'Apache httpd, et d'autre part de n'avoir besoin que de la commande apxs -i suivie d'un apachectl restart pour introduire une nouvelle version de votre module fraîchement développé dans le serveur HTTP Apache en cours d'exécution.

Inconvénients des DSO :

  • Le serveur est environ 20 % plus lent au démarrage à cause des résolutions de symboles supplémentaires que le chargeur Unix doit effectuer.
  • Le serveur est environ 5 % plus lent à l'exécution sur certaines plates-formes, car le code indépendant de la position (PIC) nécessite parfois des manipulations compliquées en assembleur pour l'adressage relatif qui ne sont pas toujours aussi rapides que celles que permet l'adressage absolu.
  • Comme les modules DSO ne peuvent pas être liés avec d'autres bibliothèques basées sur DSO (ld -lfoo) sur toutes les plates-formes (par exemple, les plates-formes basées sur a.out ne fournissent en général pas cette fonctionnalité alors que les plates-formes basées sur ELF le font), vous ne pouvez pas utiliser le mécanisme DSO pour tous les types de modules. Ou en d'autres termes, les modules compilés comme fichiers DSO sont contraints de n'utiliser que les symboles du coeur d'Apache httpd, de la bibliothèque C (libc) et toutes autres bibliothèques statiques ou dynamiques utilisées par le coeur d'Apache httpd, ou d'archives statiques (libfoo.a) contenant du code indépendant de la position (PIC). Il y a deux solutions pour utiliser un autre type de code : soit le coeur d'Apache httpd contient déjà lui-même une référence au code, soit vous chargez le code vous-même via dlopen().


Négociation de contenu - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Négociation de contenu

Apache HTTPD supporte la négociation de contenu telle qu'elle est décrite dans la spécification HTTP/1.1. Il peut choisir la meilleure représentation d'une ressource en fonction des préférences du navigateur pour ce qui concerne le type de media, les langages, le jeu de caractères et son encodage. Il implémente aussi quelques fonctionnalités pour traiter de manière plus intelligente les requêtes en provenance de navigateurs qui envoient des informations de négociation incomplètes.

La négociation de contenu est assurée par le module mod_negotiation qui est compilé par défaut dans le serveur.

À propos de la négociation de contenu

Une ressource peut être disponible selon différentes représentations. Par exemple, elle peut être disponible en différents langages ou pour différents types de média, ou une combinaison des deux. Pour faire le meilleur choix, on peut fournir à l'utilisateur une page d'index, et le laisser choisir. Cependant, le serveur peut souvent faire ce choix automatiquement. Ceci est possible car les navigateurs peuvent envoyer des informations sur les représentations qu'ils préfèrent à l'intérieur de chaque requête. Par exemple, un navigateur peut indiquer qu'il préfère voir les informations en français, mais qu'en cas d'impossibilité l'anglais peut convenir. Les navigateurs indiquent leurs préférences à l'aide d'en-têtes dans la requête. Pour ne demander que des représentations en français, le navigateur peut utiliser l'en-tête :

Accept-Language: fr

Notez qu'il ne sera tenu compte de cette préférence que s'il existe un choix de représentations et que ces dernières varient en fonction du langage.

À titre d'exemple d'une requête plus complexe, ce navigateur a été configuré pour accepter le français et l'anglais, avec une préférence pour le français, et accepter différents types de média, avec une préférence pour HTML par rapport à au texte plat ("plain text") ou autres types de fichiers texte, et avec une préférence pour GIF ou JPEG par rapport à tout autre type de média, mais autorisant tout autre type de média en dernier ressort :

Accept-Language: fr; q=1.0, en; q=0.5
Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1

httpd supporte la négociation de contenu "server driven" (telle qu'elle est définie dans la spécification HTTP/1.1), où c'est le serveur qui décide quelle est la meilleure représentation à retourner pour la ressource demandée. Il supporte entièrement les en-têtes de requête Accept, Accept-Language, Accept-Charset et Accept-Encoding. httpd supporte aussi la négociation de contenu transparente, qui est un protocole de négociation expérimental défini dans les RFC 2295 et 2296. Il ne supporte pas la négociation de fonctionnalité (feature negotiation) telle qu'elle est définie dans ces RFCs.

Une ressource est une entité conceptuelle identifiée par une URI (RFC 2396). Un serveur HTTP comme le serveur HTTP Apache propose l'accès à des représentations de la ressource à l'intérieur de son espace de nommage, chaque représentation étant composée d'une séquence d'octets avec la définition d'un type de media, d'un jeu de caractères, d'un encodage, etc... A un instant donné, chaque ressource peut être associée avec zéro, une ou plusieurs représentations. Si plusieurs représentations sont disponibles, la ressource est qualifiée de négociable et chacune de ses représentations se nomme variante. Les différences entre les variantes disponibles d'une ressource négociable constituent les dimensions de la négociation.

La négociation avec httpd

Afin de négocier une ressource, on doit fournir au serveur des informations à propos de chacune des variantes. Il y a deux manières d'accomplir ceci :

  • Utiliser une liste de correspondances de type ("type-map") (c'est à dire un fichier *.var) qui nomme explicitement les fichiers contenant les variantes, ou
  • Utiliser une recherche "multivues", où le serveur effectue une recherche de correspondance sur un motif de nom de fichier implicite et fait son choix parmi les différents résultats.

Utilisation d'un fichier de correspondances de types (type-map)

Une liste de correspondances de types est un document associé au gestionnaire type-map (ou, dans un souci de compatibilité ascendante avec des configurations de httpd plus anciennes, le type MIME application/x-type-map). Notez que pour utiliser cette fonctionnalité, vous devez, dans le fichier de configuration, définir un gestionnaire qui associe un suffixe de fichier à une type-map; ce qui se fait simplement en ajoutant

AddHandler type-map .var

dans le fichier de configuration du serveur.

Les fichiers de correspondances de types doivent posséder le même nom que la ressource qu'ils décrivent, avec pour extension .var. Dans l'exemple ci-dessous, la ressource a pour nom foo, et le fichier de correspondances se nomme donc foo.var.

Ce fichier doit comporter une entrée pour chaque variante disponible; chaque entrée consiste en une ligne contiguë d'en-têtes au format HTTP. les entrées sont séparées par des lignes vides. Les lignes vides à l'intérieur d'une entrée sont interdites. Par convention, le fichier de correspondances de types débute par une entrée concernant l'entité considérée dans son ensemble (bien que ce ne soit pas obligatoire, et ignoré si présent). Un exemple de fichier de correspondance de types est fourni ci-dessous.

Les URIs de ce fichier sont relatifs à la localisation du fichier de correspondances de types. En général, ces fichiers se trouveront dans le même répertoire que le fichier de correspondances de types, mais ce n'est pas obligatoire. Vous pouvez utiliser des URIs absolus ou relatifs pour tout fichier situé sur le même serveur que le fichier de correspondances.

URI: foo

URI: foo.en.html
Content-type: text/html
Content-language: en

URI: foo.fr.de.html
Content-type: text/html;charset=iso-8859-2
Content-language: fr, de

Notez aussi qu'un fichier de correspondances de types prend le pas sur les extensions de noms de fichiers, même si les Multivues sont activées. Si les variantes sont de qualités différentes, on doit l'indiquer à l'aide du paramètre "qs" à la suite du type de média, comme pour cette image (disponible aux formats JPEG, GIF, ou ASCII-art) :

URI: foo

URI: foo.jpeg
Content-type: image/jpeg; qs=0.8

URI: foo.gif
Content-type: image/gif; qs=0.5

URI: foo.txt
Content-type: text/plain; qs=0.01

Les valeurs de qs peuvent varier de 0.000 à 1.000. Notez que toute variante possédant une valeur de qs de 0.000 ne sera jamais choisie. Les variantes qui n'ont pas de paramètre qs défini se voient attribuer une valeur de 1.0. Le paramètre qs indique la qualité relative de la variante comparée à celle des autres variantes disponibles, sans tenir compte des capacités du client. Par exemple, un fichier JPEG possède en général une qualité supérieure à celle d'un fichier ASCII s'il représente une photographie. Cependant, si la ressource représentée est à un ASCII art original, la représentation ASCII sera de meilleure qualité que la représentation JPEG. Ainsi une valeur de qs est associée à une variante en fonction de la nature de la ressource qu'elle représente.

La liste complète des en-têtes reconnus est disponible dans la documentation sur les correspondances de types du module mod_negotiation.

Multivues (option Multiviews)

MultiViews est une option qui s'applique à un répertoire, ce qui signifie qu'elle peut être activée à l'aide d'une directive Options à l'intérieur d'une section <Directory>, <Location> ou <Files> dans httpd.conf, ou (si AllowOverride est correctement positionnée) dans des fichiers .htaccess. Notez que Options All n'active pas MultiViews; vous devez activer cette option en la nommant explicitement.

L'effet de MultiViews est le suivant : si le serveur reçoit une requête pour /tel/répertoire/foo, si MultiViews est activée pour /tel/répertoire, et si /tel/répertoire/foo n'existe pas, le serveur parcourt le répertoire à la recherche de fichiers nommés foo.*, et simule littéralement une correspondance de types (type map) qui liste tous ces fichiers, en leur associant les mêmes types de média et encodages de contenu qu'ils auraient eu si le client avait demandé l'accès à l'un d'entre eux par son nom. Il choisit ensuite ce qui correspond le mieux aux besoins du client.

MultiViews peut aussi s'appliquer à la recherche du fichier nommé par la directive DirectoryIndex, si le serveur tente d'indexer un répertoire. Si les fichiers de configuration spécifient

DirectoryIndex index

le serveur va choisir entre index.html et index.html3 si les deux fichiers sont présents. Si aucun n'est présent, mais index.cgi existe, le serveur l'exécutera.

Si, parcequ'elle n'est pas reconnue par mod_mime, l'extension d'un des fichiers du répertoire ne permet pas de déterminer son jeu de caractères, son type de contenu, son langage, ou son encodage, alors le résultat dépendra de la définition de la directive MultiViewsMatch. Cette directive détermine si les gestionnaires (handlers), les filtres, et autres types d'extensions peuvent participer à la négociation MultiVues.

Les méthodes de négociation

Une fois obtenue la liste des variantes pour une ressource donnée, httpd dispose de deux méthodes pour choisir la meilleure variante à retourner, s'il y a lieu, soit à partir d'un fichier de correspondances de types, soit en se basant sur les noms de fichiers du répertoire. Il n'est pas nécessaire de connaître en détails comment la négociation fonctionne réellement pour pouvoir utiliser les fonctionnalités de négociation de contenu de httpd. La suite de ce document explique cependant les méthodes utilisées pour ceux ou celles qui sont intéressés(ées).

Il existe deux méthodes de négociation :

  1. La négociation effectuée par le serveur selon l'algorithme de httpd est normalement utilisée. l'algorithme de httpd est expliqué plus en détails ci-dessous. Quand cet algorithme est utilisé, httpd peut parfois "bricoler" le facteur de qualité (qs) d'une dimension particulière afin d'obtenir un meilleur résultat. La manière dont httpd peut modifier les facteurs de qualité est expliquée plus en détails ci-dessous.
  2. La négociation de contenu transparente est utilisée quand le navigateur le demande explicitement selon le mécanisme défini dans la RFC 2295. Cette méthode de négociation donne au navigateur le contrôle total du choix de la meilleure variante; le résultat dépend cependant de la spécificité des algorithmes utilisés par le navigateur. Au cours du processus de négociation transparente, le navigateur peut demander à httpd d'exécuter l'"algorithme de sélection de variante à distance" défini dans la RFC 2296.

Les dimensions de la négociation

Dimension | Notes
Type de média | Le navigateur affiche ses préférences à l'aide du champ d'en-tête Accept. Chaque type de média peut se voir associé un facteur de qualité. La description de la variante peut aussi avoir un facteur de qualité (le paramètre "qs").
Langage | Le navigateur affiche ses préférences à l'aide du champ d'en-tête Accept-Language. Chaque langue peut se voir associé un facteur de qualité. Les variantes peuvent être associées avec zéro, un ou plusieurs langages.
Encoding | Le navigateur affiche ses préférences à l'aide du champ d'en-tête Accept-Encoding. Chaque encodage peut se voir associé un facteur de qualité.
Charset | Le navigateur affiche ses préférences à l'aide du champ d'en-tête Accept-Charset. Chaque jeu de caractère peut se voir associé un facteur de qualité. Les variantes peuvent préciser un jeu de caractères comme paramètre du type de média.

L'algorithme de négociation de httpd

httpd peut utiliser l'algorithme suivant pour choisir la "meilleure" variante (s'il y en a une) à retourner au navigateur. Cet algorithme n'est pas configurable. Il fonctionne comme suit :

  1. En premier lieu, pour chaque dimension de la négociation, consulter le champ d'en-tête Accept* approprié et assigner une qualité à chaque variante. Si l'en-tête Accept* pour toute dimension implique que la variante n'est pas acceptable, éliminer cette dernière. S'il ne reste plus de variante, aller à l'étape 4.
  2. Choisir la "meilleure" variante par élimination. Chacun des tests suivants est effectué dans cet ordre. Toute variante non sélectionnée à l'issue d'un test est éliminée. Après chaque test, s'il reste une seule variante, choisir cette dernière comme celle qui correspond le mieux puis aller à l'étape 3. S'il reste plusieurs variantes, passer au test suivant.
    1. Multiplier le facteur de qualité de l'en-tête Accept par le facteur de qualité "qs" pour le type de média de ces variantes, et choisir la variante qui possède la valeur la plus importante.
    2. Sélectionner les variantes qui possèdent le facteur de qualité de langage le plus haut.
    3. Sélectionner les variantes dont le langage correspond le mieux, en se basant sur l'ordre des langages de l'en-tête Accept-Language (s'il existe), ou de la directive LanguagePriority (si elle existe).
    4. Sélectionner les variantes possédant le paramètre de média "level" le plus élevé (utilisé pour préciser la version des types de média text/html).
    5. Sélectionner les variantes possédant le paramètre de média "charset" (jeu de caractères) qui correspond le mieux, en se basant sur la ligne d'en-tête Accept-Charset . Le jeu de caractères ISO-8859-1 est acceptable sauf s'il est explicitement exclus. Les variantes avec un type de média text/* mais non explicitement associées avec un jeu de caractères particulier sont supposées être en ISO-8859-1.
    6. Sélectionner les variantes dont le paramètre de média "charset" associé n'est pas ISO-8859-1. S'il n'en existe pas, sélectionner toutes les variantes.
    7. Sélectionner les variantes avec le meilleur encodage. S'il existe des variantes avec un encodage acceptable pour le client, sélectionner celles-ci. Sinon, s'il existe des variantes encodées et des variantes non encodées, ne sélectionner que les variantes non encodées. Si toutes les variantes sont encodées ou si aucune ne l'est, sélectionner toutes les variantes.
    8. Sélectionner les variantes dont le contenu a la longueur la plus courte.
    9. Sélectionner la première des variantes restantes. Il s'agira soit de la première variante listée dans le fichier de correspondances de types, soit, quand les variantes sont lues depuis le répertoire, la première par ordre alphabétique quand elles sont triées selon le code ASCII.
  3. L'algorithme a maintenant sélectionné une variante considérée comme la "meilleure", il la retourne donc au client en guise de réponse. L'en-tête HTTP Vary de la réponse est renseigné de façon à indiquer les dimensions de la négociation (les navigateurs et les caches peuvent utiliser cette information lors de la mise en cache de la ressource). Travail terminé.
  4. Le passage par cette étape signifie qu'aucune variante n'a été sélectionnée (parcequ'aucune n'est acceptable pour le navigateur). Envoyer une réponse avec un code de statut 406 (qui signifie "Aucune représentation acceptable") et un corps comportant un document HTML qui affiche les variantes disponibles. Renseigner aussi l'en-tête HTTP Vary de façon à indiquer les dimensions de la variante.

Ajustement des valeurs de qualité

Parfois httpd modifie les valeurs de qualité par rapport à celles qui découleraient d'une stricte interprétation de l'algorithme de négociation de httpd ci-dessus, ceci pour améliorer les résultats de l'algorithme pour les navigateurs qui envoient des informations incomplètes ou inappropriées. Certains des navigateurs les plus populaires envoient des informations dans l'en-tête Accept qui, sans ce traitement, provoqueraient la sélection d'une variante inappropriée dans de nombreux cas. Quand un navigateur envoie des informations complètes et correctes ces ajustements ne sont pas effectués.

Types de média et caractères génériques

L'en-tête de requête Accept: indique les types de média souhaités. Il peut aussi contenir des types de média avec caractères génériques, comme "image/*" ou "*/*" où * correspond à n'importe quelle chaîne de caractères. Ainsi une requête contenant :

Accept: image/*, */*

indiquerait que tout type de média est acceptable, avec une préférence pour les types commençant par "image/". Certains navigateurs ajoutent par défaut des types de média avec caractères génériques aux types explicitement nommés qu'ils peuvent gérer. Par exemple :

Accept: text/html, text/plain, image/gif, image/jpeg, */*

Ceci indique que les types explicitement listés sont préférés, mais qu'une représentation avec un type différent de ces derniers conviendra aussi. Les valeurs de qualités explicites, afin de préciser ce que veut vraiment le navigateur, s'utilisent comme suit :

Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01

Les types explicites n'ont pas de facteur de qualité, la valeur par défaut de leur préférence est donc de 1.0 (la plus haute). Le type avec caractères génériques */* se voit attribuer une préférence basse de 0.01, si bien que les types autres que ceux explicitement listés ne seront retournés que s'il n'existe pas de variante correspondant à un type explicitement listé.

Si l'en-tête Accept: ne contient pas aucun facteur de qualité, httpd positionne la valeur de qualité de "*/*", si present, à 0.01 pour simuler l'effet désiré. Il positionne aussi la valeur de qualité des types avec caractères génériques au format "type/*" à 0.02 (ils sont donc préférés à ceux correspondant à "*/*"). Si un type de média dans l'en-tête Accept: contient un facteur de qualité, ces valeurs spéciales ne seront pas appliquées, de façon à ce que les requêtes de navigateurs qui envoient les informations explicites à prendre en compte fonctionnent comme souhaité.

Exceptions dans la négociation du langage

A partir de la version 2.0 de httpd, certaines exceptions ont été ajoutées à l'algorithme de négociation afin de ménager une issue de secours quand la négociation ne trouve aucun langage correspondant.

Quand un client demande une page sur votre serveur, si ce dernier ne parvient pas à trouver une page dont la langue corresponde à l'en-tête Accept-language envoyé par le navigateur, il enverra au client une réponse "Aucune variante acceptable" ou "Plusieurs choix possibles". Pour éviter ces messages d'erreur, il est possible de configurer httpd de façon à ce que, dans ces cas, il ignore l'en-tête Accept-language et fournisse tout de même un document, même s'il ne correspond pas exactement à la demande explicite du client. La directive ForceLanguagePriority peut être utilisée pour éviter ces messages d'erreur et leur substituer une page dont le langage sera déterminé en fonction du contenu de la directive LanguagePriority.

Le serveur va aussi essayer d'étendre sa recherche de correspondance aux sous-ensembles de langages quand aucune correspondance exacte ne peut être trouvée. Par exemple, si un client demande des documents possédant le langage en-GB, c'est à dire anglais britannique, le standard HTTP/1.1 n'autorise normalement pas le serveur à faire correspondre cette demande à un document dont le langage est simplement en. (Notez qu'inclure en-GB et non en dans l'en-tête Accept-Language constitue une quasi-erreur de configuration, car il est très peu probable qu'un lecteur qui comprend l'anglais britannique, ne comprenne pas l'anglais en général. Malheureusement, de nombreux clients ont réellement des configurations par défaut de ce type.) Cependant, si aucune autre correspondance de langage n'est possible, et que le serveur est sur le point de retourner une erreur "Aucune variable acceptable" ou de choisir le langage défini par la directive LanguagePriority, le serveur ignorera la spécification du sous-ensemble de langage et associera la demande en en-GB à des documents en en. Implicitement, httpd ajoute le langage parent à la liste de langues acceptés par le client avec une valeur de qualité très basse. Notez cependant que si le client demande "en-GB; q=0.9, fr; q=0.8", et le serveur dispose de documents estampillés "en" et "fr", alors c'est le document "fr" qui sera retourné, tout ceci dans un souci de compatibilité avec la spécification HTTP/1.1 et afin de fonctionner efficacement avec les clients correctement configurés.

Pour supporter les techniques avancées (comme les cookies ou les chemins d'URL spéciaux) afin de déterminer le langage préféré de l'utilisateur, le module mod_negotiation reconnaît la variable d'environnement prefer-language depuis la version 2.0.47 de httpd. Si elle est définie et contient un symbole de langage approprié, mod_negotiation va essayer de sélectionner une variante correspondante. S'il n'existe pas de telle variante, le processus normal de négociation sera lancé.

Exemple

SetEnvIf Cookie "language=(.+)" prefer-language=$1
Header append Vary cookie

Extensions à la négociation de contenu transparente

httpd étend le protocole de négociation de contenu transparente (RFC 2295) comme suit. Un nouvel élément {encodage ..} est utilisé dans les listes de variantes pour marquer celles qui ne sont disponibles qu'avec un encodage de contenu spécifique. L'implémentation de l'algorithme RVSA/1.0 (RFC 2296) est étendue à la reconnaissance de variantes encodées dans la liste, et à leur utilisation en tant que variantes candidates à partir du moment où leur encodage satisfait au contenu de l'en-tête de requête Accept-Encoding. L'implémentation RVSA/1.0 n'arrondit pas les facteurs de qualité calculés à 5 décimales avant d'avoir choisi la meilleure variante.

Remarques à propos des liens hypertextes et des conventions de nommage

Si vous utilisez la négociation de langage, vous avez le choix entre différentes conventions de nommage, car les fichiers peuvent posséder plusieurs extensions, et l'ordre dans lequel ces dernières apparaissent est en général sans rapport (voir la documentation sur le module mod_mime pour plus de détails).

Un fichier type possède une extension liée au type MIME (par exemple, html), mais parfois aussi une extension liée à l'encodage (par exemple, gz), et bien sûr une extension liée au langage (par exemple, en) quand plusieurs variantes de langage sont disponibles pour ce fichier.

Exemples :

  • foo.en.html
  • foo.html.en
  • foo.en.html.gz

Ci-dessous d'autres exemples de noms de fichiers avec des liens hypertextes valides et invalides :

Nom fichier | lien valide | Lien invalide
foo.html.en | foo foo.html | -
foo.en.html | foo | foo.html
foo.html.en.gz | foo foo.html | foo.gz foo.html.gz
foo.en.html.gz | foo | foo.html foo.html.gz foo.gz
foo.gz.html.en | foo foo.gz foo.gz.html | foo.html
foo.html.gz.en | foo foo.html foo.html.gz | foo.gz

En regardant la table ci-dessus, vous remarquerez qu'il est toujours possible d'utiliser le nom de fichier sans extension dans un lien (par exemple, foo). L'avantage est de pouvoir dissimuler le type réel du fichier associé à un document et de pouvoir le modifier ultérieurement, par exemple, de html à shtml ou cgi sans avoir à mettre à jour aucun lien.

Si vous souhaitez continuer à utiliser un type MIME dans vos liens (par exemple foo.html), l'extension liée au langage (y compris une extension liée à l'encodage s'il en existe une) doit se trouver à droite de l'extension liée au type MIME (par exemple, foo.html.en).

Remarque sur la mise en cache

Quand un cache stocke une représentation, il l'associe avec l'URL de la requête. Lorsque cette URL est à nouveau demandée, le cache peut utiliser la représentation stockée. Cependant, si la ressource est négociable au niveau du serveur, il se peut que seule la première variante demandée soit mise en cache et de ce fait, la correspondance positive du cache peut entraîner une réponse inappropriée. Pour éviter ceci, httpd marque par défaut toutes les réponses qui sont retournées après une négociation de contenu comme "non-cachables" par les clients HTTP/1.0. httpd supporte aussi les fonctionnalités du protocole HTTP/1.1 afin de permettre la mise en cache des réponses négociées.

Pour les requêtes en provenance d'un client compatible HTTP/1.0 (un navigateur ou un cache), la directive CacheNegotiatedDocs peut être utilisée pour permettre la mise en cache des réponses qui ont fait l'objet d'une négociation. Cette directive peut intervenir dans la configuration au niveau du serveur ou de l'hôte virtuel, et n'accepte aucun argument. Elle n'a aucun effet sur les requêtes en provenance de clients HTTP/1.1.

Pour les clients HTTP/1.1, httpd envoie un en-tête de réponse HTTP Vary afin d'indiquer les dimensions de la négociation pour cette réponse. Les caches peuvent utiliser cette information afin de déterminer si une requête peut être servie à partir de la copie locale. Pour inciter un cache à utiliser la copie locale sans tenir compte des dimensions de la négociation, définissez la variable d'environnement force-no-vary.


Messages d'erreur personnalisés - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Messages d'erreur personnalisés

Le serveur HTTP Apache fournit des messages d'erreur génériques pour les codes de statut 4xx ou 5xx ; ces messages sont cependant relativement austères, imprécis, et peuvent s'avérer intimidants pour les visiteurs du site. Si vous le souhaitez, vous pouvez afficher des messages d'erreur plus conviviaux, dans un langage autre que l'anglais, ou même sous une forme plus en adéquation avec le style de votre site.

Il est possible de définir des messages d'erreur personnalisés pour chaque code de statut HTTP associé à une condition d'erreur - c'est à dire tout code de statut 4xx ou 5xx.

De plus, il est possible de personnaliser le message d'erreur en fonction d'un jeu de valeurs fourni, en utilisant les Inclusions Côté Serveur (SSI). Un programme CGI ou un autre gestionnaire dynamique (PHP, mod_perl, etc...) peut aussi utiliser ces variables pour gérer les conditions d'erreur.

Configuration

Les messages d'erreur personnalisés sont configurés via la directive ErrorDocument, qui peut être utilisée dans un contexte global, serveur virtuel ou répertoire. On peut utiliser cette directive dans les fichiers .htaccess si AllowOverride est définie à FileInfo.

ErrorDocument 500 "Désolé, notre script s'est
crashé ; comme c'est dommage !"
ErrorDocument 500 /cgi-bin/crash-recover
ErrorDocument 500 http://error.example.com/server_error.html
ErrorDocument 404 /errors/not_found.html
ErrorDocument 401 /subscription/how_to_subscribe.html

La syntaxe de la directive ErrorDocument est :

ErrorDocument <code_3_chiffres> <action>

où action peut être traitée comme :

  1. Une URL de redirection local (si l'action commence par un "/").
  2. Une URL de redirection externe (si action est une URL valide).
  3. Le texte à afficher (si l'action ne répond à aucune des deux conditions précédentes). Entourez le texte de guillemets (") s'il contient plusieurs mots.

Dans le cas d'une redirection vers une URL locale, des variables d'environnement supplémentaires sont définies de façon à ce que la réponse puisse être personnalisée par la suite. Elles ne sont pas envoyées aux URLs externes.

Variables disponibles

La redirection vers une autre URL peut être utile, mais seulement s'il est possible de transmettre certaines informations qui pourront être utilisées pour expliquer ou journaliser la condition d'erreur ou le problème plus clairement.

Pour y parvenir, lorsque la redirection d'erreur est envoyée, des variables d'environnement supplémentaires sont définies à partir des en-têtes de la requête originale en préfixant le nom d'origine de l'en-tête par 'REDIRECT_', ce qui permet de fournir au message d'erreur le contexte de la requête originelle.

Par exemple, en plus des variables d'environnement habituelles, vous pouvez recevoir ce qui suit :

REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png
REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8
REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=client.example.com
REDIRECT_SERVER_NAME=www.example.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/2.2.15
REDIRECT_URL=/cgi-bin/buggy.pl

Les variables d'environnement REDIRECT_ sont créées à partir des variables d'environnement préexistantes à la redirection qui sont préfixées par la chaîne REDIRECT_ ; par exemple, HTTP_USER_AGENT devient REDIRECT_HTTP_USER_AGENT.

REDIRECT_URL, REDIRECT_STATUS, et REDIRECT_QUERY_STRING sont systématiquement définies, les autres variables n'étant définies que si l'en-tête correspondant existait avant la condition d'erreur.

Aucune d'entre elles ne sera définie si votre directive ErrorDocument spécifie une redirection externe (toute URL commençant par un protocole du style http:, même si elle fait référence au même hôte que le serveur).

Personnalisation des messages d'erreur

Si vous faites pointer votre directive ErrorDocument vers certains gestionnaires dynamiques comme les inclusions côté serveur, les scripts CGI ou d'autres gestionnaires, vous pouvez utiliser les variables d'environnement supplémentaires disponibles pour personnaliser le message.

Si la directive ErrorDname-basedocument spécifie une redirection locale vers un script CGI, ce dernier doit ajouter un en-tête "Status:" dans sa sortie afin de s'assurer du bon acheminement jusqu'au client de la condition d'erreur qui a provoqué cette redirection. Par exemple, un script Perl spécifié par une directive ErrorDocument pourrait contenir ce qui suit :

...
print  "Content-type: text/html\n";
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
...

Si un script est dédié à la gestion d'une condition d'erreur spécifique, telle que 404 Not Found, il peut utiliser le code et le texte de l'erreur spécifiques à la place.

Notez que si la réponse contient un en-tête Location: (afin d'initier une redirection côté client), le script doit émettre un en-tête approprié (comme 302 Found). Dans le cas contraire, l'en-tête Location: ne produira aucun effet.

Messages d'erreur personnalisés multilingues

Vous trouverez dans la distribution du serveur HTTP Apache un répertoire contenant des messages d'erreur personnalisés traduits en 16 langues différentes. Pour activer cette fonctionnalité, vous pouvez aussi inclure un fichier de configuration qui se trouve dans le répertoire de configuration conf/extra.

Dans le fichier de configuration de votre serveur, vous trouverez un groupe de lignes du style :

    # Multi-language error messages
    #Include conf/extra/httpd-multilang-errordoc.conf

Décommentez la ligne Include pour activer cette fonctionnalité, et présenter des messages d'erreur dont le langage sera négocié en fonction du langage préféré défini au niveau du navigateur du client.

De plus, ces documents contiennent diverses variables REDIRECT_, de façon à ce que l'utilisateur final dispose d'informations supplémentaires à propos de ce qui a pu se produire, et de ce qu'il est susceptible de faire maintenant.

Ces documents peuvent être personnalisés en fournissant autant d'informations utiles que vous le souhaitez aux utilisateurs à propos de votre site, et de ce qu'ils sont susceptibles d'y trouver.

Pour pouvoir utiliser cette fonctionnalité, vous devez activer mod_include et mod_negotiation.


Ecoute sélective - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Ecoute sélective

Configuration du serveur HTTP Apache pour l'écoute sur un port et une adresse IP spécifiques.

Voir aussi

  • Hôtes virtuels
  • Problèmes liés à DNS

Vue d'ensemble

Modules Apparentés Directives Apparentées
  • core
  • mpm_common
  • <VirtualHost>
  • Listen

Au démarrage de httpd, un port et une adresse lui sont associés sur l'hôte local et le serveur se met en attente de l'arrivée d'une requête. Par défaut, le serveur écoute toutes les adresses de l'hôte local. Cependant, on peut lui préciser des ports et des adresses spécifiques à écouter, ou une combinaison des deux. Tout ceci est souvent associé avec la fonctionnalité des hôtes virtuels qui détermine la manière dont httpd répond aux différents ports, noms d'hôtes et adresses IP.

La directive Listen enjoint le serveur de n'accepter des requêtes que sur le(s) port(s) spécifiés ou une combinaison adresse/port. Si seul un numéro de port est spécifié dans la directive Listen, le serveur se met à l'écoute sur ce port, sur toutes les interfaces réseau. Si une adresse IP est spécifiée en plus du port, le serveur va écouter sur ce port, uniquement sur l'interface réseau correspondante. On peut utiliser de multiples directives Listen pour spécifier plusieurs adresses et ports à écouter. Le serveur répondra alors aux requêtes sur ces ports et adresses spécifiés.

Par exemple, pour faire en sorte que le serveur accepte des connexions sur les ports 80 et 8000, sur toutes les interfaces, utilisez :

Listen 80
Listen 8000

Pour faire en sorte que le serveur accepte des connexions sur le port 80 pour une interface, et sur le port 8000 pour une autre interface, utilisez :

Listen 192.0.2.1:80
Listen 192.0.2.5:8000

Les adresses IPv6 doivent être mises entre crochets, comme dans l'exemple suivant :

Listen [2001:db8::a00:20ff:fea7:ccea]:80

Des directives Listen imbriquées provoqueront une erreur fatale qui empêchera le serveur de démarrer.

(48)Address already in use: make_sock: could not bind to address [::]:80

Voir cette discussion dans le wiki pour plus de conseils pour résoudre ce problème.

Remarques spécifiques à IPv6

Un nombre croissant de plateformes implémentent IPv6, et APR supporte IPv6 sur la plupart d'entre elles, ce qui permet à httpd d'allouer des points de connexion (sockets) IPv6 et de traiter des requêtes envoyées sur IPv6.

Les administrateurs de httpd doivent se préoccuper de la possibilité pour un point de connexion IPv6 de traiter à la fois des connexions IPv4 et des connexions IPv6. Le traitement de connexions IPv4 avec un point de connexion IPv6 utilise des adresses IPv6 traduites en IPv4, qui sont autorisées par défaut sur la plupart des plateformes, mais sont interdites par défaut sous FreeBSD, NetBSD, et OpenBSD, afin de respecter la politique de sécurité du système sur ces plateformes. Sur les systèmes où ces adresses sont interdites par défaut, un paramètre spécial du script configure permet de modifier ce comportement pour httpd.

En revanche, sur certaines plateformes comme Linux et Tru64, la seule manière de gérer à la fois IPv6 et IPv4 passe par l'utilisation d'adresses traduites. Si vous voulez que httpd gère des connexions IPv4 et IPv6 avec un minimum de points de connexion, ce qui nécessite l'utilisation d'adresses IPv6 traduites en IPv4, utilisez l'option --enable-v4-mapped du script configure.

L'option --enable-v4-mapped est utilisée par défaut sur toutes les plateformes sauf FreeBSD, NetBSD, et OpenBSD; votre httpd a donc probablement été construit avec cette option.

Si vous souhaitez que httpd ne gère que des connexions IPv4, sans se soucier de ce que vos plateforme et APR supportent, spécifiez une adresse IPv4 dans toutes les directives Listen, comme dans l'exemple suivant :

Listen 0.0.0.0:80
Listen 192.0.2.1:80

Si votre plateforme le supporte et si vous souhaitez que httpd gère des connexions IPv4 et IPv6 sur des points de connexion séparés (c'est à dire désactiver la traduction des adresses IPv6 au format IPv4), utilisez l'option --disable-v4-mapped du script configure. --disable-v4-mapped est utilisé par défaut sur FreeBSD, NetBSD, et OpenBSD.

Spécification du protocole avec Listen

Dans la plupart des configurations, le second paramètre optionnel protocol de la directive Listen n'est pas obligatoire. S'il n'est pas spécifié, les protocoles par défaut sont https pour le port 443, et http pour tous les autres ports. Le protocole sert à déterminer quel module doit traiter une requête, et à appliquer les optimisations spécifiques au protocole via la directive AcceptFilter.

Vous ne devez définir le protocole que si vous travaillez avec des ports non standards. Par exemple, pour travailler en https sur le port 8443 :

Listen 192.170.2.1:8443 https

Comment tout ceci fonctionne-t-il avec les hôtes virtuels

La directive Listen n'implémente pas les hôtes virtuels. Elle indique simplement au serveur principal sur quels adresses et ports il doit écouter. Si aucune directive <VirtualHost> n'est présente, le serveur se comportera de la même façon pour toutes les requêtes acceptées. En revanche, la directive <VirtualHost> peut être utilisée pour provoquer une réaction différente du serveur pour un ou plusieurs adresses ou ports. Pour implémenter un hôte virtuel, on doit d'abord indiquer au serveur sur quels adresses et ports il doit écouter. Ensuite, une section <VirtualHost> doit être créée pour le couple adresse+port spécifié afin de définir le comportement de cet hôte virtuel. Notez que si la directive <VirtualHost> est définie pour une adresse et un port sur lesquels le serveur n'est pas censé écouter, cet hôte virtuel ne sera pas accessible.


Modules multi-processus (MPMs) - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Modules multi-processus (MPMs)

Ce document décrit ce qu'est un Module Multi-Processus, ainsi que la manière dont ces modules sont utilisés par le serveur HTTP Apache.

Introduction

La conception du serveur HTTP Apache en fait un serveur web puissant et flexible pouvant fonctionner sur une très grande variété de plateformes et toute une gamme d'environnements différents. Plateformes différentes et environnements différents signifient souvent fonctionnalités différentes, ou utilisation de différentes méthodes pour implémenter la même fonctionnalité le plus efficacement possible. Apache httpd s'est toujours accomodé d'une grande variété d'environnements grâce à sa conception modulaire. Cette conception autorise le webmaster à choisir quelles fonctionnalités seront incluses dans le serveur en sélectionnant les modules à charger soit à la compilation, soit à l'exécution.

Le serveur HTTP Apache 2.0 a étendu cette conception modulaire aux fonctions les plus élémentaires d'un serveur web. Le serveur est fourni avec une variété de Modules Multi-Processus (MPMs) qui sont responsables de l'association aux ports réseau de la machine, acceptent les requêtes, et se chargent de répartir ces dernières entre les différents processus enfants.

L'extension de la conception modulaire à ce niveau du serveur comporte deux avantages importants :

  • Apache httpd peut supporter plus proprement et efficacement une grande variété de systèmes d'exploitation. En particulier, la version Windows du serveur est maintenant beaucoup plus efficace, depuis que mpm_winnt peut utiliser les fonctionnalités réseau natives à la place de la couche POSIX utilisée par Apache httpd 1.3. Cet avantage s'étend aussi aux systèmes d'exploitation qui implémentent des MPMs spécialisés.
  • le serveur est plus à même de répondre aux besoins d'un site particulier. Par exemple, les sites qui sont très sollicités peuvent utiliser un MPM threadé comme worker ou event, tandis que les sites qui privilégient la stabilité ou la compatibilité avec des logiciels plus anciens peuvent utiliser un module comme prefork.

Du point de vue de l'utilisateur, les MPMs ne sont pas différents des autres modules Apache httpd. La principale différence réside dans le fait qu'un et un seul MPM à la fois doit être chargé lorsque le serveur s'exécute. La liste des MPMs disponibles est fournie dans l'index des modules.

MPM par défaut

La table suivante fournit la liste des MPMs par défaut pour divers systèmes d'exploitation. Il s'agit du MPM qui sera utilisé si vous n'en spécifiez pas un autre à la compilation.

Netware | mpm_netware
OS/2 | mpmt_os2
Unix | prefork, worker, ou event, selon les possibilités de la plate-forme
Windows | mpm_winnt

Ici, 'Unix' sous-entend les systèmes d'exploitation de type Unix, comme Linux, BSD, Solaris, Mac OS X, etc...

Dans le cas des systèmes d'exploitation de type Unix, le choix du MPM à installer est orienté par deux questions :

1. Est-ce que le système supporte les threads ?

2. Est-ce que le système supporte le polling thread-safe (et en particulier les fonctions kqueue et epoll) ?

Si la réponse aux deux questions est 'oui', le MPM par défaut sera event.

Si la réponse à la première question est 'oui', et la réponse à la deuxième 'non', le MPM par défaut sera worker.

Si la réponse aux deux questions est 'non', le MPM par défaut sera prefork.

En pratique, cela signifie que le MPM par défaut sera presque toujours event car tous les systèmes d'exploitation modernes satisfont aux deux conditions.

Compiler un module MPM en tant que module statique

Les modules MPM peuvent être compilés en tant que modules statiques sur toutes les plates-formes. A la compilation d'Apache, un seul module MPM doit être choisi pour être compilé et lié avec le serveur. La recompilation du serveur sera donc nécessaire si vous souhaitez changer de module MPM.

Pour choisir un module MPM autre que le MPM par défaut, utiliser l'argument --with-mpm=NOM du script configure. NOM est le nom du MPM désiré.

Une fois le serveur compilé, il est possible de savoir quel MPM a été choisi à l'aide de la commande ./httpd -l. Cette commande fournit la liste de tous les modules compilés avec le serveur, y compris le MPM.

Compiler un module MPM en tant que module DSO (Dynamic Shared Object)

Sous Unix et les plates-formes similaires, les modules MPM peuvent être compilés en tant que modules DSO et chargés dynamiquement dans le serveur comme tout module DSO. Compiler les modules MPM en tant que modules DSO permet de changer de MPM en modifiant la directive LoadModule concernée, sans avoir à recompiler le serveur.

LoadModule mpm_prefork_module modules/mod_mpm_prefork.so

Toute tentative de charger plusieurs modules MPM via la directive LoadModule empêchera le serveur de démarrer et affichera l'erreur suivante :

AH00534: httpd: Configuration error: More than one MPM loaded.

Cette fonctionnalité est activée via l'option --enable-mpms-shared du script configure. Si on ajoute l'argument all, tous les modules MPM disponibles sur la plate-forme considérée seront installés. Cet argument peut aussi contenir une liste de modules MPM à installer.

Le module MPM par défaut, sélectionné automatiquement ou spécifié via l'option --with-mpm du script configure, sera chargé via une directive LoadModule du fichier de configuration du serveur généré. Pour choisir un autre module MPM, vous devrez donc modifier cette directive


Apache et les variables d'environnement - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Apache et les variables d'environnement

Deux types de variables d'environnement affectent le serveur HTTP Apache.

Le premier type correspond aux variables d'environnement contrôlées par le système d'exploitation sous-jacent et définies avant le démarrage du serveur. Leurs valeurs peuvent être utilisées directement dans les fichiers de configuration, et peuvent éventuellement être transmises aux scripts CGI et SSI via la directive PassEnv.

Le second type correspond aux variables nommées appelées aussi variables d'environnement dans lesquelles le serveur HTTP Apache stocke des informations via un mécanisme spécial. Ces informations peuvent servir à contrôler diverses opérations comme l'enregistrement des traces ou le contrôle d'accès. On utilise aussi ces variables dans le mécanisme de communication avec les programmes externes comme les scripts CGI. Ce document présente différentes méthodes pour manipuler et utiliser ces variables.

Bien que ces variables soient référencées comme variables d'environnement, il ne faut pas les confondre avec les variables d'environnement contrôlées par le système d'exploitation sous-jacent. En fait, ces variables sont stockées et manipulées dans une structure interne à Apache. Elles ne deviennent de véritables variables d'environnement du système d'exploitation que lorsqu'elles sont mises à la disposition de scripts CGI et de scripts inclus côté serveur (SSI). Si vous souhaitez manipuler l'environnement du système d'exploitation sous lequel le serveur s'exécute, vous devez utiliser les mécanismes standards de manipulation de l'environnement fournis par l'interpréteur de commandes (shell) de votre système d'exploitation.

Définition des variables d'environnement

Modules Apparentés Directives Apparentées
  • mod_cache
  • mod_env
  • mod_rewrite
  • mod_setenvif
  • mod_unique_id
  • BrowserMatch
  • BrowserMatchNoCase
  • PassEnv
  • RewriteRule
  • SetEnv
  • SetEnvIf
  • SetEnvIfNoCase
  • UnsetEnv

Manipulations de base de l'environnement

La méthode la plus élémentaire pour définir une variable d'environnement au niveau d'Apache consiste à utiliser la directive inconditionnelle SetEnv. Les variables peuvent aussi être transmises depuis l'environnement du shell à partir duquel le serveur a été démarré en utilisant la directive PassEnv.

Définitions conditionnelles en fonction des requêtes

Pour plus de souplesse, les directives fournies par le module mod_setenvif permettent de définir les variables d'environnement en tenant compte des caractéristiques de chaque requête. Par exemple, une variable pourrait n'être définie que lorsqu'un navigateur spécifique (User-Agent) a généré la requête, ou seulement quand un en-tête Referer particulier est présent. La directive RewriteRule du module mod_rewrite qui utilise l'option [E=...] pour définir les variables d'environnement apporte encore plus de souplesse.

Identifiants uniques

Finalement, le module mod_unique_id définit la variable d'environnement UNIQUE_ID pour chaque requête à une valeur qui est garantie unique parmi "toutes" les requêtes sous des conditions très spécifiques.

Variables CGI standards

En plus de l'ensemble des variables d'environnement internes à la configuration d'Apache et de celles transmises depuis le shell, les scripts CGI et les pages SSI se voient affectés un ensemble de variables d'environnement contenant des méta-informations à propos de la requête comme préconisé dans la spécification sur les CGIs.

Quelques mises en garde

  • Les directives de manipulation de l'environnement ne permettent pas de supplanter ou modifier les variables CGI standards.
  • Lorsqu'on utilise suexec pour exécuter des scripts CGI, l'environnement est nettoyé et réduit à un ensemble de variables sûres avant l'exécution du script. La liste des variables sûres est définie à la compilation dans suexec.c.
  • Pour des raisons de portabilité, les noms des variables d'environnement ne peuvent contenir que des lettres, des chiffres, et le caractère "sousligné". En outre, le premier caractère ne doit pas être un chiffre. Les caractères qui ne satisfont pas à ces conditions seront remplacés par un caractère "sousligné" quand ils seront transmis aux scripts CGI et aux pages SSI.
  • Les contenus d'en-têtes HTTP transmis aux scripts de type CGI ou autre via des variables d'environnement constituent un cas particulier (voir plus loin). Leur nom est converti en majuscules et seuls les tirets sont remplacés par des caractères '_' ("souligné") ; si le format du nom de l'en-tête n'est pas valide, celui-ci est ignoré. Voir plus loin pour une solution de contournement du problème.
  • La directive SetEnv s'exécute assez tard au cours du traitement de la requête, ce qui signifie que des directives telles que SetEnvIf et RewriteCond ne verront pas les variables qu'elle aura définies.
  • Lorsque le serveur cherche un chemin via une sous-requête interne (par exemple la recherche d'un DirectoryIndex), ou lorsqu'il génère un listing du contenu d'un répertoire via le module mod_autoindex, la sous-requête n'hérite pas des variables d'environnement spécifiques à la requête. En outre, à cause des phases de l'API auxquelles mod_setenvif prend part, les directives SetEnvIf ne sont pas évaluées séparément dans la sous-requête.

Utilisation des variables d'environnement

Modules Apparentés Directives Apparentées
  • mod_authz_host
  • mod_cgi
  • mod_ext_filter
  • mod_headers
  • mod_include
  • mod_log_config
  • mod_rewrite
  • Require
  • CustomLog
  • Deny
  • ExtFilterDefine
  • Header
  • LogFormat
  • RewriteCond
  • RewriteRule

Scripts CGI

La communication d'informations aux scripts CGI constitue une des principales utilisations des variables d'environnement. Comme indiqué plus haut, l'environnement transmis aux scripts CGI comprend des méta-informations standards à propos de la requête, en plus des variables définies dans la configuration d'Apache. Pour plus de détails, se référer au tutoriel CGI.

Pages SSI

Les documents inclus côté serveur (SSI) traités par le filtre INCLUDES du module mod_include, peuvent afficher les variables d'environnement à l'aide de l'élément echo, et peuvent utiliser des variables d'environnement dans les éléments de contrôle de flux pour rendre certaines parties d'une page conditionnelles en fonction des caractéristiques de la requête. Apache fournit aussi les variables d'environnement CGI standards aux pages SSI comme indiqué plus haut. Pour plus de détails, se référer au tutoriel SSI.

Contrôle d'accès

L'accès au serveur peut être contrôlé en fonction de la valeur de variables d'environnement à l'aide des directives allow from env= et deny from env=. En association avec la directive SetEnvIf, ceci confère une grande souplesse au contrôle d'accès au serveur en fonction des caractéristiques du client. Par exemple, vous pouvez utiliser ces directives pour interdire l'accès depuis un navigateur particulier (User-Agent).

Enregistrement conditionnel des traces

Les variables d'environnement peuvent être enregistrées dans le fichier de log des accès à l'aide de l'option %e de la directive LogFormat. En outre, la décision de tracer ou non les requêtes peut être prise en fonction de l'état de variables d'environnement en utilisant la forme conditionnelle de la directive CustomLog. En association avec la directive SetEnvIf, ceci confère une grande souplesse au contrôle du traçage des requêtes. Par exemple, vous pouvez choisir de ne pas tracer les requêtes pour des noms de fichiers se terminant par gif, ou encore de ne tracer que les requêtes des clients n'appartenant pas à votre sous-réseau.

En-têtes de réponse conditionnels

La directive Header peut se baser sur la présence ou l'absence d'une variable d'environnement pour décider si un certain en-tête HTTP sera placé dans la réponse au client. Ceci permet, par exemple, de n'envoyer un certain en-tête de réponse que si un en-tête correspondant est présent dans la requête du client.

Activation de filtres externes

Les filtres externes configurés par le module mod_ext_filter à l'aide de la directive ExtFilterDefine peuvent être activés de manière conditionnelle en fonction d'une variable d'environnement à l'aide des options disableenv= et enableenv=.

Réécriture d'URL

La forme %{ENV:variable} de TestString dans la directive RewriteCond permet au moteur de réécriture du module mod_rewrite de prendre des décisions conditionnées par des variables d'environnement. Notez que les variables accessibles dans mod_rewrite sans le préfixe ENV: ne sont pas de véritables variables d'environnement. Ce sont plutôt des variables spécifiques à mod_rewrite qui ne sont pas accessibles pour les autres modules.

Variables d'environnement à usage spécial

Des problèmes d'interopérabilité ont conduit à l'introduction de mécanismes permettant de modifier le comportement d'Apache lorsqu'il dialogue avec certains clients. Afin de rendre ces mécanismes aussi souples que possible, ils sont invoqués en définissant des variables d'environnement, en général à l'aide de la directive BrowserMatch, bien que les directives SetEnv et PassEnv puissent aussi être utilisées, par exemple.

downgrade-1.0

Ceci force le traitement d'une requête comme une requête HTTP/1.0 même si elle a été rédigée dans un langage plus récent.

force-gzip

Si le filtre DEFLATE est activé, cette variable d'environnement ignorera les réglages accept-encoding de votre navigateur et enverra une sortie compressée inconditionnellement.

force-no-vary

Cette variable entraîne la suppression de tout champ Vary des en-têtes de la réponse avant que cette dernière soit renvoyée au client. Certains clients n'interprètent pas ce champ correctement, et la définition de cette variable permet de contourner ce problème, mais implique aussi la définition de force-response-1.0.

force-response-1.0

Cette variable force une réponse en langage HTTP/1.0 aux clients qui envoient des requêtes dans le même langage. Elle fut implémentée à l'origine suite à des problèmes avec les mandataires d'AOL. Certains clients en langage HTTP/1.0 ne réagissent pas correctement face à une réponse en langage HTTP/1.1, et cette variable peut être utilisée pour assurer l'interopérabilité avec eux.

gzip-only-text/html

Positionnée à "1", cette variable désactive le filtre en sortie DEFLATE fourni par le module mod_deflate pour les types de contenu autres que text/html. Si vous préférez utiliser des fichiers compressés statiquement, mod_negotiation évalue aussi la variable (non seulement pour gzip, mais aussi pour tous les encodages autres que "identity").

no-gzip

Quand cette variable est définie, le filtre DEFLATE du module mod_deflate est désactivé, et mod_negotiation refusera de délivrer des ressources encodées.

no-cache

Disponible dans les versions 2.2.12 et ultérieures d'Apache

Lorsque cette variable est définie, mod_cache ne sauvegardera pas de réponse susceptible d'être mise en cache. Cette variable d'environnement n'a aucune incidence sur le fait qu'une réponse déjà enregistrée dans la cache soit utilisée ou non pour la requête courante.

nokeepalive

Quand cette variable est définie, la directive KeepAlive est désactivée.

prefer-language

Cette variable modifie le comportement du module mod_negotiation. Si elle contient un symbole de langage (tel que en, ja ou x-klingon), mod_negotiation essaie de délivrer une variante dans ce langage. S'il n'existe pas de telle variante, le processus normal de négociation s'applique.

redirect-carefully

Cette variable force le serveur à être plus prudent lors de l'envoi d'une redirection au client. Elle est en général utilisée quand un client présente un problème connu avec les redirections. Elle fut implémentée à l'origine suite a un problème rencontré avec le logiciel WebFolders de Microsoft qui ne gère pas correctement les redirections vers des ressources de type répertoire via des méthodes DAV.

suppress-error-charset

Disponible dans les versions postérieures à 2.0.54

Quand Apache génère une redirection en réponse à une requête client, la réponse inclut un texte destiné à être affiché au cas où le client ne suivrait pas, ou ne pourrait pas suivre automatiquement la redirection. Habituellement, Apache marque ce texte en accord avec le jeu de caractères qu'il utilise, à savoir ISO-8859-1.

Cependant, si la redirection fait référence à une page qui utilise un jeu de caractères différent, certaines versions de navigateurs obsolètes essaieront d'utiliser le jeu de caractères du texte de la redirection plutôt que celui de la page réelle. Ceci peut entraîner, par exemple, un rendu incorrect du Grec.

Si cette variable d'environnement est définie, Apache omettra le jeu de caractères pour le texte de la redirection, et les navigateurs obsolètes précités utiliseront correctement celui de la page de destination.

Note concernant la sécurité

L'envoi de pages d'erreur sans spécifier un jeu de caractères peut conduire à des attaques de type "cross-site-scripting" pour les navigateurs qui ne respectent pas la spécification HTTP/1.1 (MSIE) et tentent de déduire le jeu de caractères à partir du contenu. De tels navigateurs peuvent être facilement trompés et utiliser le jeu de caractères UTF-7 ; les contenus des données en entrée de type UTF-7 (comme les URI de requête) ne seront alors plus protégés par les mécanismes d'échappement usuels conçus pour prévenir les attaques de type "cross-site-scripting".

force-proxy-request-1.0, proxy-nokeepalive, proxy-sendchunked, proxy-sendcl, proxy-chain-auth, proxy-interim-response, proxy-initial-not-pooled

Ces directives modifient le comportement protocolaire du module mod_proxy. Voir la documentation sur mod_proxy et mod_proxy_http pour plus de détails.

Exemples

Transmission du contenu d'en-têtes non valides aux scripts CGI

Avec la version 2.4, Apache est plus strict avec la conversion des en-têtes HTTP en variables d'environnement dans mod_cgi et d'autres modules : dans les versions précédentes, tout caractère invalide dans les noms d'en-têtes était tout simplement remplacé par un caractère '_', ce qui pouvait exposer à des attaques de type cross-site-scripting via injection d'en-têtes (voir Bogues du Web inhabituelles, planche 19/20).

Si vous devez supporter un client qui envoie des en-têtes non conformes et si ceux-ci ne peuvent pas être corrigés, il existe une solution de contournement simple mettant en jeu les modules mod_setenvif et mod_headers, et permettant de prendre en compte ces en-têtes :

# L'exemple suivant montre comment prendre en compte un en-tête

# Accept_Encoding non conforme envoyé par un client.
#
SetEnvIfNoCase ^Accept.Encoding$ ^(.*)$ fix_accept_encoding=$1
RequestHeader set Accept-Encoding %{fix_accept_encoding}e env=fix_accept_encoding

Modification du comportement protocolaire face à des clients réagissant de manière non conforme

Les versions antérieures recommandaient l'ajout de ces lignes dans httpd.conf pour tenir compte de problèmes connus avec certains clients. Comme les clients concernés sont maintenant très peu utilisés, cet ajout n'est pratiquement plus nécessaire.

#
# The following directives modify normal HTTP response behavior.
# The first directive disables keepalive for Netscape 2.x and browsers that
# spoof it. There are known problems with these browser implementations.
# The second directive is for Microsoft Internet Explorer 4.0b2
# which has a broken HTTP/1.1 implementation and does not properly
# support keepalive when it is used on 301 or 302 (redirect) responses.
#
BrowserMatch "Mozilla/2" nokeepalive
BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0

#
# The following directive disables HTTP/1.1 responses to browsers which
# are in violation of the HTTP/1.0 spec by not being able to grok a
# basic 1.1 response.
#
BrowserMatch "RealPlayer 4\.0" force-response-1.0
BrowserMatch "Java/1\.0" force-response-1.0
BrowserMatch "JDK/1\.0" force-response-1.0

Ne pas tracer les requêtes pour des images dans le fichier de trace des accès

Dans cet exemple, les requêtes pour des images n'apparaissent pas dans le fichier de trace des accès. Il peut être facilement adapté pour empêcher le traçage de répertoires particuliers, ou de requêtes en provenance de certains hôtes.

SetEnvIf Request_URI \.gif image-request
SetEnvIf Request_URI \.jpg image-request
SetEnvIf Request_URI \.png image-request
CustomLog logs/access_log common env=!image-request

Prévention du "Vol d'image"

Cet exemple montre comment empêcher les utilisateurs ne faisant pas partie de votre serveur d'utiliser des images de votre serveur comme images en ligne dans leurs pages. Cette configuration n'est pas recommandée, mais elle peut fonctionner dans des circonstances bien définies. Nous supposons que toutes vos images sont enregistrées dans un répertoire nommé /web/images.

SetEnvIf Referer "^http://www\.example\.com/" local_referal
# Autorise les navigateurs qui n'envoient aucune information de Referer
SetEnvIf Referer "^$" local_referal
<Directory "/web/images">
    Require env local_referal
</Directory>

Pour plus d'informations sur cette technique, voir le tutoriel sur ServerWatch "Keeping Your Images from Adorning Other Sites".


Les expressions dans le serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Les expressions dans le serveur HTTP Apache

Historiquement, il existe de nombreuses variantes dans la syntaxe des expressions permettant d'exprimer une condition dans les différents modules du serveur HTTP Apache. À ce titre, des travaux sont en cours pour n'utiliser qu'une seule variante nommée ap_expr, pour toutes les directives de configuration. Ce document décrit l'interpréteur d'expressions ap_expr.

Le type d'expression ap_expr est appelé à remplacer la plupart des autres types d'expressions dans HTTPD. Par exemple, la directive obsolète SSLRequire peut être remplacée par la directive Require expr.

Voir aussi

  • If
  • <If>
  • <ElseIf>
  • <Else>
  • ErrorDocument
  • Alias
  • ScriptAlias
  • Redirect
  • AuthBasicFake
  • AuthFormLoginRequiredLocation
  • AuthFormLoginSuccessLocation
  • AuthFormLogoutLocation
  • RewriteCond
  • SetEnvIfExpr
  • Header
  • RequestHeader
  • FilterProvider
  • Require expr
  • Require ldap-user
  • Require ldap-group
  • Require ldap-dn
  • Require ldap-attribute
  • Require ldap-filter
  • Require dbd-group
  • Require dbm-group
  • Require group
  • Require host
  • SSLRequire
  • LogMessage
  • mod_include

Syntaxe en Forme de Backus-Naur

La Forme de Backus-Naur (souvent abrégée en BNF, de l'anglais Backus-Naur Form) est une notation permettant de décrire les règles syntaxiques des langages de programmation. En général, les expressions représentent des valeurs booléennes. Dans ce cas, le point de départ de la BNF est expr. Cependant, certaines directives comme LogMessage utilisent comme paramètres des expressions qui représentent des chaînes de caractères. Dans ce cas, le point de départ de la BNF est string.

expr        ::= "true" | "false"
              | "!" expr
              | expr "&&" expr
              | expr "||" expr
              | "(" expr ")"
              | comp

comp        ::= stringcomp
              | integercomp
              | unaryop word
              | word binaryop word
              | word "in" "{" wordlist "}"
              | word "in" listfunction
              | word "=~" regex
              | word "!~" regex

stringcomp  ::= word "==" word
              | word "!=" word
              | word "<"  word
              | word "<=" word
              | word ">"  word
              | word ">=" word

integercomp ::= word "-eq" word | word "eq" word
              | word "-ne" word | word "ne" word
              | word "-lt" word | word "lt" word
              | word "-le" word | word "le" word
              | word "-gt" word | word "gt" word
              | word "-ge" word | word "ge" word

wordlist    ::= word
              | wordlist "," word

word        ::= word "." word
              | digit
              | "'" string "'"
              | """ string """
              | variable
          | rebackref
              | function

string      ::= stringpart
              | string stringpart

stringpart  ::= cstring
              | variable
          | rebackref

cstring     ::= ...
digit       ::= [0-9]+

variable    ::= "%{" varname "}"
              | "%{" funcname ":" funcargs "}"

rebackref   ::= "$" [0-9]

function     ::= funcname "(" word ")"

listfunction ::= listfuncname "(" word ")"

Variables

L'interpréteur d'expressions fournit plusieurs variables de la forme %{HTTP_HOST}. Notez que la valeur d'une variable peut dépendre de la phase du traitement de la requête au cours de laquelle elle est évaluée. Par exemple, une expression utilisée dans une directive <If > sera évaluée avant la phase d'authentification. Par conséquent, la variable %{REMOTE_USER} ne sera pas encore définie à ce stade.

Les variables suivantes contiennent la valeur de l'en-tête de requête HTTP correspondant. La fonction req permet d'extraire les valeurs des autres en-têtes. L'utilisation de ces variables peut provoquer l'ajout du nom d'en-tête correspondant à l'en-tête Vary de la réponse HTTP, sauf spécification contraire pour la directive qui accepte l'expression comme paramètre. La function req_novary permet de modifier ce comportement.

Nom
HTTP_ACCEPT
HTTP_COOKIE
HTTP_FORWARDED
HTTP_HOST
HTTP_PROXY_CONNECTION
HTTP_REFERER
HTTP_USER_AGENT

Autres variables liées aux requêtes

Nom | Description
REQUEST_METHOD | La méthode HTTP de la requête entrante (par exemple GET)
REQUEST_SCHEME | Le protocole associé à l'URI de la requête
REQUEST_URI | La partie chemin de l'URI de la requête
DOCUMENT_URI | Idem REQUEST_URI
REQUEST_FILENAME | Le chemin complet dans le système de fichiers local du fichier ou du script correspondant à la requête, si le serveur l'a dèjà déterminé à l'instant où REQUEST_FILENAME est référencée. Dans le cas contraire, comme dans un contexte de serveur virtuel, même valeur que REQUEST_URI
SCRIPT_FILENAME | Identique à REQUEST_FILENAME
LAST_MODIFIED | La date et heure de dernière modification du fichier au format 20101231235959, si elle est déjà connue du serveur au moment où LAST_MODIFIED est référencé.
SCRIPT_USER | Le nom d'utilisateur du propriétaire du script.
SCRIPT_GROUP | Le nom du groupe auquel appartient le script.
PATH_INFO | L'information relative au nom de chemin située en fin, voir la directive AcceptPathInfo
QUERY_STRING | La chaîne de paramètres de la requête courante
IS_SUBREQ | "true" si la requête courante est une sous-requête, "false" dans le cas contraire
THE_REQUEST | La requête complète (par exemple "GET /index.html HTTP/1.1")
REMOTE_ADDR | L'adresse IP de l'hôte distant
REMOTE_PORT | Le port de l'hôte distant (versions 2.4.26 et supérieures)
REMOTE_HOST | Le nom d'hôte de l'hôte distant
REMOTE_USER | Le nom de l'utilisateur authentifié, s'il existe (non disponible à l'intérieur d'un bloc <If >)
REMOTE_IDENT | Le nom de l'utilisateur défini par mod_ident
SERVER_NAME | La valeur de la directive ServerName du serveur virtuel courant
SERVER_PORT | Le port associé au serveur virtuel courant ; voir la directive ServerName
SERVER_ADMIN | La valeur de la directive ServerAdmin du serveur virtuel courant
SERVER_PROTOCOL | Le protocole utilisé par la requête
DOCUMENT_ROOT | La valeur de la directive DocumentRoot du serveur virtuel courant
AUTH_TYPE | La valeur de la directive AuthType (par exemple "basic")
CONTENT_TYPE | Le type de contenu de la réponse (non disponible à l'intérieur d'un bloc <If >)
HANDLER | Le nom du gestionnaire qui a généré la réponse
HTTP2 | "on" si la requête utilise http/2, "off" dans le cas contraire
HTTPS | "on" si la requête utilise https, "off" dans le cas contraire
IPV6 | "on" si la connexion utilise IPv6, "off" dans le cas contraire
REQUEST_STATUS | Le code d'erreur HTTP de la requête (non disponible à l'intérieur d'un bloc <If >)
REQUEST_LOG_ID | L'identifiant du message d'erreur associé à la requête (voir la directive ErrorLogFormat)
CONN_LOG_ID | L'identifiant du message d'erreur associé à la connexion (voir la directive ErrorLogFormat)
CONN_REMOTE_ADDR | L'adresse IP du correspondant pour la connexion (voir le module mod_remoteip)
CONTEXT_PREFIX |
CONTEXT_DOCUMENT_ROOT |

Variables diverses

Nom | Description
TIME_YEAR | L'année courante (par exemple 2010)
TIME_MON | Le mois courant (01, ..., 12)
TIME_DAY | Le jour courant dans le mois (01, ...)
TIME_HOUR | Les heures de la date courante (00, ..., 23)
TIME_MIN | Les minutes de la date courante
TIME_SEC | Les secondes de la date courante
TIME_WDAY | Le jour de la semaine (à partir de 0 pour dimanche)
TIME | La date et heure au format 20101231235959
SERVER_SOFTWARE | La chaîne contenant la version du serveur
API_VERSION | La date de la version de l'API (module magic number)

Certains modules, comme mod_ssl, définissent des variables supplémentaires.

Opérateurs binaires

À l'exception de quelques opérateurs de comparaison internes, les opérateurs binaires sont de la forme "-[a-zA-Z][a-zA-Z0-9_]+", autrement dit un signe moins et au moins deux caractères. Le nom est insensible à la casse. Les modules peuvent fournir des opérateurs binaires supplémentaires.

Opérateurs de comparaison

Nom | Alternative | Description
== | = | Egalité de chaînes
!= |  | Inégalité de chaînes
< |  | Chaîne inférieure à
<= |  | Chaîne inférieure ou égale à
> |  | Chaîne supérieure à
>= |  | Chaîne supérieure ou égale à
=~ |  | La chaîne correspond à l'expression rationnelle
!~ |  | La chaîne ne correspond pas à l'expression rationnelle
-eq | eq | Egalité d'entiers
-ne | ne | Inégalité d'entiers
-lt | lt | Entier inférieur à
-le | le | Entier inférieur ou égal à
-gt | gt | Entier supérieur à
-ge | ge | Entier supérieur ou égal à

Autres opérateurs binaires

Nom | Description
-ipmatch | L'adresse IP correspond à adresse/masque
-strmatch | la chaîne de gauche correspond au modèle constitué par la chaîne de droite (contenant des caractères génériques *, ?, [])
-strcmatch | idem -strmatch, mais insensible à la casse
-fnmatch | idem -strmatch, mais les slashes ne sont pas pris en compte par les caractères génériques

Opérateurs unaires

Les opérateurs unaires acceptent un seul argument et sont de la forme "-[a-zA-Z]", autrement dit le signe moins et un caractère. Le nom est sensible à la casse. Les modules peuvent fournir des opérateurs unaires supplémentaires.

Nom | Description | Remarques particulières
-d | L'argument est traité comme un nom de fichier. Vrai si le fichier existe et correspond à un répertoire | oui
-e | L'argument est traité comme un nom de fichier. Vrai si le fichier (ou dir ou special) existe | oui
-f | L'argument est traité comme un nom de fichier. Vrai si le fichier existe et correspond à un fichier régulier | oui
-s | L'argument est traité comme un nom de fichier. Vrai si le fichier existe et n'est pas vide | oui
-L | L'argument est traité comme un nom de fichier. Vrai si le fichier existe et correspond à un lien symbolique | oui
-h | L'argument est traité comme un nom de fichier. Vrai si le fichier existe et correspond à un lien symbolique (identique à -L) | oui
-F | Vrai si la chaîne correspond a un fichier valide, accessible avec tous les contrôles d'accès configurés pour ce chemin. A cette fin, une sous-requête effectue la vérification, et vous devez utiliser ce drapeau avec soin car il peut impacter les performances de votre serveur ! |
-U | Vrai si la chaîne correspond a une URL valide, accessible avec tous les contrôles d'accès configurés pour ce chemin. A cette fin, une sous-requête effectue la vérification, et vous devez utiliser ce drapeau avec soin car il peut impacter les performances de votre serveur ! |
-A | Alias pour -U |
-n | Vrai si la chaîne n'est pas vide |
-z | Vrai si la chaîne est vide |
-T | Faux si la chaîne est vide, "0", "off", "false", ou "no" (insensibilité à la casse). Vrai dans le cas contraire. |
-R | Idem "%{REMOTE_ADDR} -ipmatch ...", en plus efficace |

Les opérateurs marqués comme "restreints" ne sont pas disponibles avec certains modules comme mod_include.

Fonctions

Normalement, les fonctions dont la valeur est une chaîne acceptent une chaîne comme argument et renvoient une chaîne. Les noms de fonctions sont insensibles à la casse. Les modules peuvent fournir des fonctions supplémentaires.

Nom | Description | Notes particulières
req, http | Lit l'en-tête de requête HTTP ; les noms d'en-tête correspondants peuvent être ajoutés à l'en-tête Vary, voir ci-dessous |
req_novary | Identique à req, mais aucun nom d'en-tête n'est ajouté à l'en-tête Vary |
resp | Lit l'en-tête de réponse HTTP |
reqenv | Recherche une variable d'environnement de requête (on peut aussi utiliser le raccourci v). | ordonnancement
osenv | Recherche une variable d'environnement du système d'exploitation |
note | Recherche une note de requête | ordonnancement
env | Renvoie le premier résultat positif de note, reqenv, osenv | ordonnancement
tolower | Convertit une chaîne en minuscules |
toupper | Convertit une chaîne en majuscules |
escape | Echappe les caractères spéciaux en codage hexadécimal |
unescape | "Déséchappe" les chaînes codées en hexadécimal, en ne gardant encodés que les slashes; renvoie la chaîne vide si la séquence %00 est rencontrée |
base64 | Encode la chaîne en base64 |
unbase64 | Décode les chaînes codées en base64, renvoie une chaîne tronquée si le caractère 0x00 est rencontré |
md5 | Génère un hash de la chaîne en utilisant MD5, puis code le hash obtenu en hexadécimal |
sha1 | Génère un hash de la chaîne en utilisant SHA1, puis encode le hash obtenu en hexadécimal |
file | Lit le contenu d'un fichier(fins de lignes incluses, si elles existent) | limité
filemod | Renvoie la date de dernière modification d'un fichier (ou 0 si le fichier n'existe pas ou n'est pas un fichier régulier) | limité
filesize | Renvoie la taille d'un fichier (ou 0 si le fichier n'existe pas ou ne correspond pas à un fichier régulier) | limité

Les fonctions marquées comme "limité" dans la dernière colonne ne sont pas disponibles avec certains modules comme mod_include.

Les fonctions marquées comme "ordonnancement" dans la dernière colonne nécessitent une attention particulière pour l'ordonnancement des différents composants du serveur, spécialement lorsque la fonction est utilisée au sein d'une directive <If> qui est évaluée relativement tôt.

Ordonnancement des variables d'environnement

Lorsque des variables d'environnement sont évaluées au sein d'une directive <If>, il est important de tenir compte du moment où cette évaluation intervient dans le traitement de la requête. Par exemple, toute directive définie en dehors d'un contexte de serveur virtuel (directory, location, htaccess) aura peu de chance d'être déjà exécutée. Ainsi la directive SetEnvIf est une directive qui s'exécute avant cette évaluation.

Lorsque reqenv est utilisé en dehors de la directive <If>, l'évaluation survient en général plus tard, mais le moment exact dépend de la directive dans laquelle l'expression a été utilisée.

Lorsque les fonctions req ou http sont utilisées, le nom d'en-tête sera automatiquement ajouté à l'en-tête Vary de la réponse HTTP, sauf spécification contraire pour la directive qui accepte l'expression comme paramètre. La fonction req_novary permet d'empêcher l'ajout de noms d'en-têtes à l'en-tête Vary.

En plus des fonctions dont la valeur est une chaîne, il existe aussi des fonctions dont la valeur est une liste, qui acceptent une chaîne comme argument, et renvoient une liste de mots, autrement dit une liste de chaînes. La liste de mot peut être utilisée avec l'opérateur spécial -in. Les noms de fonctions sont insensibles à la casse. Les modules peuvent fournir des fonctions supplémentaires.

Il n'existe pas de fonctions internes dont la valeur est une liste. Le module mod_ssl fournit la fonction PeerExtList. Voir la description de la directive SSLRequire pour plus de détails (notez que la fonction PeerExtList peut aussi être utilisée en dehors de la directive SSLRequire).

Exemples d'expressions

Les exemples suivants montent comment utiliser les expressions pour évaluer les requêtes :

# Comparer le nom d'hôte avec example.com et rediriger vers
# www.example.com si le nom d'hôte correspond
<If "%{HTTP_HOST} == 'example.com'">
    Redirect permanent "/" "http://www.example.com/"
</If>

# Forcer le type text/plain si un fichier fait l'objet d'une
# requête dont la chaîne de paramètres contient 'forcetext'
<If "%{QUERY_STRING} =~ /forcetext/">
    ForceType text/plain
</If>

# N'autoriser l'accès à ce contenu que pendant les heures de
# travail
<Directory "/foo/bar/business">
     Require expr %{TIME_HOUR} -gt 9 && %{TIME_HOUR} -lt 17
</Directory>

# Vérifie si un en-tête HTTP correspond à une des valeurs d'une liste
<If "%{HTTP:X-example-header} in { 'foo', 'bar', 'baz' }">
    La définition de l'en-tête correspond à une des valeurs recherchées
</If>

# Recherche la valeur d'une expression rationnelle dans une variable
# d'environnement, et renvoie la négation du résultat.
<If "! reqenv('REDIRECT_FOO') =~ /bar/">
    La condition est vérifiée
</If>

# Vérifie le résultat de la recherche d'une correspondance d'URI dans un
# contexte de répertoire avec l'option -f
<Directory "/var/www">
    AddEncoding x-gzip gz
<If "-f '%{REQUEST_FILENAME}.unzipme' && ! %{HTTP:Accept-Encoding} =~ /gzip/">
      SetOutputFilter INFLATE
</If>
</Directory>

# Vérifie l'adresse IP du client
<If "-R '192.168.1.0/24'">
    Header set matched true
</If>

# Exemple de fonction dans un contexte booléen
<If "md5('foo') == 'acbd18db4cc2f85cedef654fccc4a4d8'">
  Header set checksum-matched true
</If>

# Function example in string context
Header set foo-checksum "expr=%{md5:foo}"

# L'exemple suivant retarde l'évaluation de la clause de condition par rapport à
# <If>
Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path\.php$#"

Autres

Nom | Alternative | Description
-in | in | chaîne contenue dans une liste de mots
/regexp/ | m#regexp# | Expression rationnelle (la seconde forme permet de spécifier des délimiteurs autres que /)
/regexp/i | m#regexp#i | Expression rationnelle insensible à la casse
$0 ... $9 |  | Références arrières dans les expressions rationnelles

Références arrières dans les expressions rationnelles

Les chaînes $0 ... $9 permettent de référencer les groupes de capture en provenance d'expressions rationnelles précédemment exécutées et mises en correspondance avec succès. Elles ne peuvent normalement être utilisées que dans la même expression que celle mise en correspondance, mais certains modules permettent de les utiliser de manière spéciale.

Comparaison avec SSLRequire

La syntaxe ap_expr consiste principalement en une surcouche de la syntaxe de la directive obsolète SSLRequire. Vous pouvez consulter la liste de leur différences dans la documentation de la directive SSLRequire.

Historique de version

La fonction req_novary est disponible à partir de la version 2.4.4 du serveur HTTP Apache.


Utilisation des gestionnaires d'Apache (handlers) - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Utilisation des gestionnaires d'Apache (handlers)

Ce document décrit l'utilisation des gestionnaires d'Apache (handlers).

Qu'est-ce qu'un gestionnaire ?

Modules Apparentés Directives Apparentées
  • mod_actions
  • mod_asis
  • mod_cgi
  • mod_imagemap
  • mod_info
  • mod_mime
  • mod_negotiation
  • mod_status
  • Action
  • AddHandler
  • RemoveHandler
  • SetHandler

Un "gestionnaire" est une représentation interne à Apache de l'action qui doit être entreprise quand un fichier est appelé. En général, les fichiers ont des gestionnaires implicites, basés sur le type du fichier. Normalement, tous les fichiers sont traités simplement par le serveur, mais certains types de fichiers sont "gérés" séparément.

Les gestionnaires peuvent aussi être configurés explicitement, soit en fonction des extensions des noms de fichier, soit en fonction du chemin du fichier, sans faire référence au type de fichier. Ceci a le double avantage d'être une solution plus élégante, et aussi d'autoriser à associer à la fois un type et un gestionnaire avec un fichier. (Voir aussi Fichiers avec extensions multiples.)

Les gestionnaires peuvent être soit partie intégrante du serveur ou inclus dans un module, soit ajoutés à l'aide de la directive Action. Les gestionnaires intégrés dans la distribution standard se présentent comme suit :

  • default-handler: envoie le fichier en utilisant le default_handler(), qui est le gestionnaire utilisé par défaut pour traiter les contenus statiques. (core)
  • send-as-is: envoie les fichiers avec en-têtes HTTP tels quels. (mod_asis)
  • cgi-script: traite le fichier comme un script CGI. (mod_cgi)
  • imap-file: Traite le fichier comme un ensemble de règles de descriptions d'images (imagemap). (mod_imagemap)
  • server-info: Extrait des informations sur la configuration du serveur. (mod_info)
  • server-status: Rédige un rapport sur le statut du serveur. (mod_status)
  • type-map: Traite le fichier comme une description de type pour la négociation du contenu. (mod_negotiation)

Exemples

Modification d'un contenu statique à l'aide d'un script CGI

Les directives suivantes vont faire en sorte que les requêtes pour des fichiers possédant une extension html déclenchent l'exécution du script CGI footer.pl.

Action add-footer /cgi-bin/footer.pl
AddHandler add-footer .html

À ce moment-là, le script CGI se charge d'envoyer le document initialement demandé (référencé par la variable d'environnement PATH_TRANSLATED) et d'effectuer tous ajout ou modification voulus.

Fichiers avec en-têtes HTTP

Les directives suivantes vont activer le gestionnaire send-as-is, qui est utilisé pour les fichiers qui possèdent leurs propres en-têtes HTTP. Tous les fichiers situés dans le répertoire /web/htdocs/asis/ seront traités par le gestionnaire send-as-is, sans tenir compte de l'extension de leur nom de fichier.

<Directory "/web/htdocs/asis">
    SetHandler send-as-is
</Directory>

Note du développeur

Pour implémenter la fonctionnalité des gestionnaires, l' API Apache a fait l'objet d'un ajout que vous pourriez être amené à utiliser. Plus précisément, un nouvel enregistrement a été ajouté à la structure request_rec :

char *handler

Si vous voulez que votre module déclenche l'utilisation d'un gestionnaire, il vous suffit de définir r->handler avec le nom du gestionnaire à n'importe quel moment avant l'étape invoke_handler de la requête. Les gestionnaires sont implémentés comme auparavant, quoique l'on utilise le nom du gestionnaire à la place d'un type de contenu. Bien que ce ne soit pas obligatoire, la convention de nommage des gestionnaires stipule l'utilisation d'un mot composé séparé par des tirets, sans slashes, afin de ne pas interférer avec l'espace de nommage des types de média.


Filtres - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Filtres

Ce document décrit l'utilisation des filtres avec Apache.

Le filtrage avec Apache 2

Modules Apparentés Directives Apparentées
  • mod_filter
  • mod_deflate
  • mod_ext_filter
  • mod_include
  • mod_charset_lite
  • mod_reflector
  • mod_buffer
  • mod_data
  • mod_ratelimit
  • mod_reqtimeout
  • mod_request
  • mod_sed
  • mod_substitute
  • mod_xml2enc
  • mod_proxy_html
  • FilterChain
  • FilterDeclare
  • FilterProtocol
  • FilterProvider
  • AddInputFilter
  • AddOutputFilter
  • RemoveInputFilter
  • RemoveOutputFilter
  • ReflectorHeader
  • ExtFilterDefine
  • ExtFilterOptions
  • SetInputFilter
  • SetOutputFilter

La chaîne de filtrage est disponible depuis la version 2.0 d'Apache, et permet aux applications de traiter les données en entrée et en sortie d'une manière hautement flexible et configurable, quelle que soit la provenance de ces données. Il est possible de pré-traiter les données en entrée, et post-traiter les données en sortie, selon vos souhaits. Ces traitements sont tout à fait indépendants des traditionnelles phases de traitement des requêtes.

les filtres peuvent s'enchaîner, perpendiculairement au traitement des requêtes

Voici quelques exemples de filtrage avec la distribution standard d'Apache:

  • mod_include, implémente les inclusions côté serveur.
  • mod_ssl, implémente le cryptage SSL (https).
  • mod_deflate, implémente la compression/décompression à la volée.
  • mod_charset_lite, transcodage entre différents jeux de caractères.
  • mod_ext_filter, utilisation d'un programme externe comme filtre.

Apache utilise aussi plusieurs filtres en interne pour accomplir des tâches comme le découpage des grosses requêtes (chunking) et la gestion des requêtes portant sur une partie d'un fichier (byte-range).

Un grand choix d'applications sont implémentées par des modules de filtrage tiers disponibles à modules.apache.org entre autres. En voici quelques exemples :

  • Traitement et réécriture HTML et XML
  • Transformations XSLT et inclusions XML (XIncludes)
  • Support de l'espace de nommage XML
  • Gestion du chargement de fichier et décodage des formulaires HTML
  • Traitement d'image
  • Protection des applications vulnérables comme les scripts PHP
  • Edition de texte par Chercher/Remplacer

Filtrage intelligent

Le filtrage intelligent applique différents fournisseurs de filtrage en fonction de l'état du traitement de la requête

mod_filter, inclus dans les version 2.1 et supérieures d'Apache, permet de configurer la chaîne de filtrage dynamiquement à l'exécution. Ainsi par exemple, vous pouvez définir un proxy pour réécrire du code HTML avec un filtre HTML et traiter des images JPEG avec un filtre totalement séparé, bien que le proxy ne possède aucune information préliminaire sur ce que le serveur à l'origine des données à filtrer va envoyer. Ceci fonctionne grâce à l'utilisation d'un gestionnaire de filtre, qui distribue les tâches à différents fournisseurs de filtrage en fonction du contenu réel à filtrer à l'exécution. Tout filtre peut se voir soit inséré directement dans la chaîne et lancé inconditionnellement, soit utilisé comme un fournisseur de filtrage et inséré dynamiquement. Par exemple,

  • un filtre de traitement HTML sera lancé uniquement si le contenu est de type text/html ou application/xhtml+xml
  • Un filtre de compression sera lancé uniquement si les données en entrée sont de type compressible et non déjà compressées
  • Un filtre de conversion de jeux de caractères ne sera inséré que si le document texte n'est pas déjà dans le jeu de caractères voulu

Présentation des filtres en tant que service HTTP

Les filtres permettent de traiter les requêtes des clients avant traitement par le serveur, ainsi que les contenus issus du serveur avant de les renvoyer au client. Le module mod_reflector permet aussi d'utiliser les filtres pour traiter les requêtes des clients avant de les renvoyer directement à ces derniers.

Le module mod_reflector reçoit les requêtes POST des clients, et en répercute le corps dans la requête POST constituant la réponse, lors de l'envoi de cette dernière au client en passant à travers la pile de filtres en sortie.

Cette technique peut être utilisée comme alternative à un service web s'exécutant à l'intérieur de la pile d'un serveur d'applications, où un filtre en sortie effectue la transformation requise sur le corps de la requête. Par exemple, on peut utiliser le module mod_deflate pour fournir un service général de compression ; un filtre de transformation d'images peut aussi se voir mué en service de transformation d'images.

Utilisation des filtres

Il y a deux manières d'utiliser le filtrage : Simple et Dynamique. En général, vous utiliserez l'une ou l'autre méthode; le mélange des deux peut avoir des conséquences inattendues (bien que le filtrage simple en entrée puisse être associé sans problème avec le filtrage simple ou dynamique en sortie).

La méthode Simple est la seule permettant de configurer les filtres en entrée, et suffit pour les filtres en sortie pour lesquels vous avez besoin d'une chaîne de filtres statique. Les directives correspondantes sont SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter, et RemoveOutputFilter.

La méthode Dynamique permet une configuration dynamique des filtres en sortie à la fois statique et flexible, comme discuté dans la page mod_filter. Les directives correspondantes sont FilterChain, FilterDeclare, et FilterProvider.

Une autre directive AddOutputFilterByType est encore supportée, mais obsolète. Utilisez la configuration dynamique à la place.


Le cache des objets partagés du serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Le cache des objets partagés du serveur HTTP Apache

Le cache des objets partagés est un concept de partage de données de base entre tous les processus d'un serveur, sans se préoccuper du modèle de threads et de processus. On l'utilise lorsque les avantages apportés par le partage de données entre processus contrebalance la perte de performances consécutive à la communication interprocessus.

Fournisseurs du cache d'objets partagés

Le cache d'objets partagés en tant que tel est une abstraction. Il est implémenté par quatre modules différents. Pour pouvoir utiliser le cache, un ou plusieurs de ces modules doivent être présents et configurés.

Le seul élément de configuration consiste à définir le fournisseur de cache à utiliser. Ceci est de la responsabilité des modules qui utilisent le cache, et pour cela, ils activent la sélection via des directives telles que CacheSocache, AuthnCacheSOCache, SSLSessionCache, et SSLStaplingCache.

Les fournisseurs actuellement disponibles sont :

"dbm" (mod_socache_dbm)
Celui-ci utilise un fichier de hashage DBM. Le choix de la DBM sous-jacente peut être configurable si la version d'APR installée supporte de multiples implémentations de DBM.
"dc" (mod_socache_dc)
Celui-ci utilise les bibliothèques de mise en cache de sessions distribuées distcache.
"memcache" (mod_socache_memcache)
Celui-ci utilise le système à hautes performances de mise en cache d'objets de mémoire distribuée memcached.
"shmcb" (mod_socache_shmcb)
Celui-ci utilise un tampon cyclique à hautes performances au sein d'un segment de mémoire partagée.

L'API fournit les fonctions suivantes :

const char *create(ap_socache_instance_t **instance, const char *arg, apr_pool_t *tmp, apr_pool_t *p);
Cette fonction permet de créer un cache de session basé sur la chaîne de configuration spécifiée. Le pointeur d'instance renvoyé dans le paramètre instance sera passé comme premier argument des invocations subséquentes.
apr_status_t init(ap_socache_instance_t *instance, const char *cname, const struct ap_socache_hints *hints, server_rec *s, apr_pool_t *pool)
Cette fonction permet d'initialiser le cache. L'argument cname doit avoir une longueur maximale de 16 caractères et permet d'identifier de manière unique l'utilisateur du cache au sein du serveur ; il est recommandé d'utiliser le nom du module, par exemple "mod_ssl-sess". Comme cette chaîne peut être utilisée au sein d'un système de fichiers, il est conseillé de n'utiliser que des caractères alphanumériques [a-z0-9_-]. Si l'argument hints n'est pas égal à NULL, il fournit un ensemble d'indications au fournisseur. La valeur retournée est le code d'erreur APR.
void destroy(ap_socache_instance_t *instance, server_rec *s)
Cette fonction permet de détruire l'instance de cache spécifiée.
apr_status_t store(ap_socache_instance_t *instance, server_rec *s, const unsigned char *id, unsigned int idlen, apr_time_t expiry, unsigned char *data, unsigned int datalen, apr_pool_t *pool)
Cette fonction permet de stocker un objet dans une instance de cache.
apr_status_t retrieve(ap_socache_instance_t *instance, server_rec *s, const unsigned char *id, unsigned int idlen, unsigned char *data, unsigned int *datalen, apr_pool_t *pool)
Cette fonction permet d'extraire un objet du cache.
apr_status_t remove(ap_socache_instance_t *instance, server_rec *s, const unsigned char *id, unsigned int idlen, apr_pool_t *pool)
Supprime un objet du cache.
void status(ap_socache_instance_t *instance, request_rec *r, int flags)
Renvoie le statut d'une instance de cache à destination de mod_status.
apr_status_t iterate(ap_socache_instance_t *instance, server_rec *s, void *userctx, ap_socache_iterator_t *iterator, apr_pool_t *pool)
Envoie tous les objets gardés en cache à une fonction pour traitement itératif.


Support suEXEC - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Support suEXEC

La fonctionnalité suEXEC permet l'exécution des programmes CGI et SSI sous un utilisateur autre que celui sous lequel s'exécute le serveur web qui appelle ces programmes. Normalement, lorsqu'un programme CGI ou SSI est lancé, il s'exécute sous le même utilisateur que celui du serveur web qui l'appelle.

Utilisée de manière appropriée, cette fonctionnalité peut réduire considérablement les risques de sécurité encourus lorsqu'on autorise les utilisateurs à développer et faire s'exécuter des programmes CGI ou SSI de leur cru. Cependant, mal configuré, suEXEC peut causer de nombreux problèmes et même créer de nouvelles failles dans la sécurité de votre ordinateur. Si vous n'êtes pas familier avec la gestion des programmes setuid root et les risques de sécurité qu'ils comportent, nous vous recommandons vivement de ne pas tenter d'utiliser suEXEC.

Avant de commencer

Avant de foncer tête baissée dans la lecture de ce document, vous devez tenir compte de certaines hypothèses concernant vous-même et l'environnement dans lequel vous allez utiliser suexec.

Premièrement, vous devez utiliser un système d'exploitation UNIX ou dérivé, capable d'effectuer des opérations setuid et setgid. Tous les exemples de commande sont donnés en conséquence. D'autres plates-formes, même si elles supportent suEXEC, peuvent avoir une configuration différente.

Deuxièmement, vous devez être familier avec les concepts de base relatifs à la sécurité de votre ordinateur et son administration. Ceci implique la compréhension des opérations setuid/setgid et des différents effets qu'elles peuvent produire sur votre système et son niveau de sécurité.

Troisièmement, vous devez utiliser une version non modifiée du code de suEXEC. L'ensemble du code de suEXEC a été scruté et testé avec soin par les développeurs et de nombreux bêta testeurs. Toutes les précautions ont été prises pour s'assurer d'une base sûre de code non seulement simple, mais aussi solide. La modification de ce code peut causer des problèmes inattendus et de nouveaux risques de sécurité. Il est vivement recommandé de ne pas modifier le code de suEXEC, à moins que vous ne soyez un programmeur spécialiste des particularités liées à la sécurité, et souhaitez partager votre travail avec l'équipe de développement du serveur HTTP Apache afin de pouvoir en discuter.

Quatrièmement et dernièrement, l'équipe de développement du serveur HTTP Apache a décidé de ne PAS inclure suEXEC dans l'installation par défaut d'Apache httpd. Pour pouvoir mettre en oeuvre suEXEC, l'administrateur doit porter la plus grande attention aux détails. Après avoir bien réfléchi aux différents points de la configuration de suEXEC, l'administrateur peut l'installer selon les méthodes classiques. Les valeurs des paramètres de configuration doivent être déterminées et spécifiées avec soin par l'administrateur, afin de maintenir la sécurité du système de manière appropriée lors de l'utilisation de la fonctionnalité suEXEC. C'est par le biais de ce processus minutieux que nous espérons réserver l'installation de suEXEC aux administrateurs prudents et suffisamment déterminés à vouloir l'utiliser.

Vous êtes encore avec nous ? Oui ? Bien. Alors nous pouvons continuer !

Modèle de sécurité de suEXEC

Avant d'installer et configurer suEXEC, nous allons tout d'abord décrire le modèle de sécurité que vous êtes sur le point d'implémenter. Vous devriez ainsi mieux comprendre ce qui se passe vraiment à l'intérieur de suEXEC et quelles précautions ont été prises pour préserver la sécurité de votre système.

suEXEC est basé sur un programme "conteneur" (wrapper) setuid qui est appelé par le serveur HTTP Apache principal. Ce conteneur est appelé quand une requête HTTP concerne un programme CGI ou SSI que l'administrateur a décidé de faire s'exécuter sous un utilisateur autre que celui du serveur principal. Lorsqu'il reçoit une telle requête, Apache httpd fournit au conteneur suEXEC le nom du programme, ainsi que les identifiants utilisateur et groupe sous lesquels le programme doit s'exécuter.

Le conteneur effectue ensuite les vérifications suivantes afin de déterminer la réussite ou l'échec du processus -- si une seule de ces conditions n'est pas vérifiée, le programme journalise l'erreur et se termine en retournant un code d'erreur, sinon il continue :

  1. L'utilisateur qui exécute le conteneur est-il un utilisateur valide de ce système ?

    Ceci permet de s'assurer que l'utilisateur qui exécute le conteneur est vraiment un utilisateur appartenant au système.

  2. Le conteneur a-t-il été appelé avec un nombre d'arguments correct ?

    Le conteneur ne s'exécutera que si on lui fournit un nombre d'arguments correct. Le serveur HTTP apache sait quel est le bon format des arguments. Si le conteneur ne reçoit pas un nombre d'arguments correct, soit il a été modifié, soit quelque chose ne va pas dans la portion suEXEC de votre binaire Apache httpd.

  3. Cet utilisateur valide est-il autorisé à exécuter le conteneur ?

    Cet utilisateur est-il celui autorisé à exécuter le conteneur ? Un seul utilisateur (celui d'Apache) est autorisé à exécuter ce programme.

  4. Le chemin du programme CGI ou SSI cible est-il non sûr ?

    Le chemin du programme CGI ou SSI cible débute-t-il par un '/' ou contient-il une référence arrière '..' ? Ceci est interdit ; le programme CGI ou SSI cible doit se trouver dans la hiérarchie de la racine des documents de suEXEC (voir --with-suexec-docroot=DIR ci-dessous).

  5. Le nom utilisateur cible est-il valide ?

    L'utilisateur cible existe-t-il ?

  6. Le nom du groupe cible est-il valide ?

    Le groupe cible existe-t-il ?

  7. L'utilisateur cible n'est-il PAS superutilisateur ?

    suEXEc ne permet pas à root d'exécuter des programmes CGI/SSI.

  8. Le numéro de l'identifiant de l'utilisateur cible est-il SUPERIEUR au numéro d'identifiant minimum ?

    Le numéro d'identifiant utilisateur minimum est défini à l'exécution du script configure. Ceci vous permet de définir le numéro d'identifiant utilisateur le plus bas qui sera autorisé à éxécuter des programmes CGI/SSI. En particulier, cela permet d'écarter les comptes système.

  9. Le groupe cible n'est-il PAS le groupe superutilisateur ?

    Actuellement, suEXEC ne permet pas au groupe root d'exécuter des programmes CGI/SSI.

  10. Le numéro d'identifiant du groupe cible est-il SUPERIEUR au numéro d'identifiant minimum ?

    Le numéro d'identifiant de groupe minimum est spécifié lors de l'exécution du script configure. Ceci vous permet de définir l'identifiant de groupe le plus bas possible qui sera autorisé à exécuter des programmes CGI/SSI, et est particulièrement utile pour écarter les groupes "système".

  11. Le conteneur peut-il obtenir avec succès l'identité des utilisateur et groupe cibles ?

    C'est ici que le programme obtient l'identité des utilisateur et groupe cibles via des appels à setuid et setgid. De même, la liste des accès groupe est initialisée avec tous les groupes auxquels l'utilisateur cible appartient.

  12. Peut-on se positionner dans le répertoire dans dequel sont situés les programmes CGI/SSI ?

    S'il n'existe pas, il ne peut pas contenir de fichier. Et si l'on ne peut pas s'y positionner, il n'existe probablement pas.

  13. Le répertoire est-il dans l'espace web de httpd ?

    Si la requête concerne une portion de la racine du serveur, le répertoire demandé est-il dans la hiérarchie de la racine des documents de suEXEC ? Si la requête concerne un UserDir, le répertoire demandé est-il dans la hiérarchie du répertoire défini comme le répertoire utilisateur de suEXEC (voir les options de configuration de suEXEC) ?

  14. L'écriture dans le répertoire est-elle interdite pour un utilisateur autre que le propriétaire

    Le répertoire ne doit pas être ouvert aux autres utilisateurs ; seul l'utilisateur propriétaire doit pouvoir modifier le contenu du répertoire.

  15. Le programme CGI/SSI cible existe-t-il ?

    S'il n'existe pas, il ne peut pas être exécuté.

  16. Les utilisateurs autres que le propriétaire n'ont-ils PAS de droits en écriture sur le programme CGI/SSI ?

    Les utilisateurs autres que le propriétaire ne doivent pas pouvoir modifier le programme CGI/SSI.

  17. Le programme CGI/SSI n'est-il PAS setuid ou setgid ?

    Les programmes cibles ne doivent pas pouvoir modifier à nouveau les identifiants utilisateur/groupe.

  18. Le couple utilisateur/groupe cible est-il le même que celui du programme ?

    L'utilisateur est-il le propriétaire du fichier ?

  19. Peut-on nettoyer avec succès l'environnement des processus afin de garantir la sûreté des opérations ?

    suExec nettoie l'environnement des processus en établissant un chemin d'exécution sûr (défini lors de la configuration), et en ne passant que les variables dont les noms font partie de la liste de l'environnement sûr (créée de même lors de la configuration).

  20. Le conteneur peut-il avec succès se substituer au programme CGI/SSI cible et s'exécuter ?

    C'est là où l'exécution de suEXEC s'arrête et où commence celle du programme CGI/ssi cible.

Ce sont les opérations standards effectuées par le modèle de sécurité du conteneur suEXEC. Il peut paraître strict et est susceptible d'imposer de nouvelles limitations et orientations dans la conception des programmes CGI/SSI, mais il a été développé avec le plus grand soin, étape par étape, en se focalisant sur la sécurité.

Pour plus d'informations sur la mesure dans laquelle ce modèle de sécurité peut limiter vos possibilités au regard de la configuration du serveur, ainsi que les risques de sécurité qui peuvent être évités grâce à une configuration appropriée de suEXEC, se référer à la section "Avis à la population !" de ce document.

Configurer et installer suEXEC

C'est ici que nous entrons dans le vif du sujet.

Options de configuration de suEXEC

--enable-suexec
Cette option active la fonctionnalité suEXEC qui n'est jamais installée ou activée par défaut. Au moins une option --with-suexec-xxxxx doit accompagner l'option --enable-suexec pour qu'APACI (l'utilitaire de configuration de la compilation d'Apache) accepte votre demande d'utilisation de la fonctionnalité suEXEC.
--with-suexec-bin=PATH
Le chemin du binaire suexec doit être codé en dur dans le serveur pour des raisons de sécurité. Cette option vous permet de modifier le chemin par défaut. Par exemple --with-suexec-bin=/usr/sbin/suexec
--with-suexec-caller=UID
L'utilisateur sous lequel httpd s'exécute habituellement. C'est le seul utilisateur autorisé à exécuter le wrapper suEXEC.
--with-suexec-userdir=DIR
Cette option définit le sous-répertoire de la hiérarchie des répertoires utilisateurs dans lequel l'utilisation de suEXEC sera autorisée. Tous les exécutables situés dans ce répertoire seront exécutables par suEXEC sous l'utilisateur cible ; ces programmes doivent donc être sûrs. Si vous utilisez une directive UserDir "simple" (c'est à dire ne contenant pas de "*"), l'option --with-suexec-userdir devra contenir la même valeur. SuEXEC ne fonctionnera pas correctement si la directive UserDir contient une valeur différente du répertoire home de l'utilisateur tel qu'il est défini dans le fichier passwd. la valeur par défaut est "public_html".
Si vous avez plusieurs hôtes virtuels avec une directive UserDir différente pour chacun d'entre eux, vous devrez faire en sorte que chaque UserDir possède un répertoire parent commun ; donnez alors à l'option --with-suexec-userdir le nom de ce répertoire commun. Si tout ceci n'est pas défini correctement, les requêtes CGI "~userdir" ne fonctionneront pas !
--with-suexec-docroot=DIR
Cette option fonctionne comme la directive DocumentRoot pour httpd. Il s'agit de la seule hiérarchie (en dehors des directives UserDir) dans laquelle la fonctionnalité suEXEC pourra être utilisée. La valeur par défaut est la valeur de --datadir accompagnée du suffixe "/htdocs" ; Par exemple, si vous exécutez configure avec "--datadir=/home/apache", la valeur "/home/apache/htdocs" sera utilisée par défaut comme racine des documents pour le conteneur suEXEC.
--with-suexec-uidmin=UID
Cette option définit l'identifiant utilisateur le plus bas avec lequel un utilisateur pourra être la cible de suEXEC. 500 ou 100 sont des valeurs courantes sur la plupart des systèmes. la valeur par défaut est 100.
--with-suexec-gidmin=GID
Cette option définit l'identifiant de groupe le plus bas avec lequel un utilisateur pourra être la cible de suEXEC. 100 est une valeur courante sur la plupart des systèmes et est par conséquent la valeur par défaut.
--with-suexec-logfile=FILE
Cette option permet de définir le fichier dans lequel toutes les transactions et erreurs de suEXEC seront journalisées (à des fins d'analyse ou de débogage). Par défaut, le fichier journal se nomme "suexec_log" et se trouve dans votre répertoire standard des fichiers journaux défini par --logfiledir
--with-suexec-safepath=PATH
Cette option permet de définir une variable d'environnement PATH sûre à passer aux exécutables CGI. La valeur par défaut est "/usr/local/bin:/usr/bin:/bin".

Compilation et installation du conteneur suEXEC

Si vous avez activé la fonctionnalité suEXEC à l'aide de l'option --enable-suexec, le binaire suexec sera automatiquement construit (en même temps que httpd) lorsque vous exécuterez la commande make.

Lorsque tous les composants auront été construits, vous pourrez exécuter la commande make install afin de les installer. Le binaire suexec sera installé dans le répertoire défini à l'aide de l'option --sbindir. La localisation par défaut est "/usr/local/apache2/bin/suexec".

Veuillez noter que vous aurez besoin des privilèges root pour passer l'étape de l'installation. Pour que le conteneur puisse changer l'identifiant utilisateur, il doit avoir comme propriétaire root, et les droits du fichier doivent inclure le bit d'exécution setuserid.

>Mise en place de permissions pour paranoïaque

Bien que le conteneur suEXEC vérifie que l'utilisateur qui l'appelle correspond bien à l'utilisateur spécifié à l'aide de l'option --with-suexec-caller du programme configure, il subsiste toujours le risque qu'un appel système ou une bibliothèque fasse appel à suEXEC avant que cette vérification ne soit exploitable sur votre système. Pour tenir compte de ceci, et parce que c'est en général la meilleure pratique, vous devez utiliser les permissions du système de fichiers afin de vous assurer que seul le groupe sous lequel s'exécute httpd puisse faire appel à suEXEC.

Si, par exemple, votre serveur web est configuré pour s'exécuter en tant que :

User www
Group webgroup

et suexec se trouve à "/usr/local/apache2/bin/suexec", vous devez exécuter les commandes

chgrp webgroup /usr/local/apache2/bin/suexec
chmod 4750 /usr/local/apache2/bin/suexec

Ceci permet de s'assurer que seul le groupe sous lequel httpd s'exécute (ici webgroup) puisse faire appel au conteneur suEXEC.

Activation et désactivation de suEXEC

Au démarrage, httpd vérifie la présence du fichier suexec dans le répertoire défini par l'option --sbindir du script configure (le répertoire par défaut est "/usr/local/apache/sbin/suexec"). Si httpd trouve un conteneur suEXEC correctement configuré, il enregistrera le message suivant dans le journal des erreurs :

[notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)

Si ce message n'est pas généré au démarrage du serveur, ce dernier ne trouve probablement pas le programme conteneur à l'endroit où il est sensé être, ou l'exécutable suexec n'est pas installé en setuid root.

Si le serveur HTTP Apache est déjà en cours d'exécution, et si vous activez le mécanisme suEXEC pour la première fois, vous devez arrêter et redémarrer httpd. Un redémarrage à l'aide d'un simple signal HUP ou USR1 suffira.

Pour désactiver suEXEC, vous devez supprimer le fichier suexec, puis arrêter et redémarrer httpd.

Utilisation de suEXEC

Les requêtes pour des programmes CGI ne feront appel au conteneur suEXEC que si elles concernent un hôte virtuel contenant une directive SuexecUserGroup, ou si elles sont traitées par mod_userdir.

Hôtes virtuels :
Une des méthodes d'utilisation du conteneur suEXEC consiste à insérer une directive SuexecUserGroup dans une section VirtualHost. En définissant des valeurs différentes de celles du serveur principal, toutes les requêtes pour des ressources CGI seront exécutées sous les User et Group définis pour cette section <VirtualHost>. Si cette directive est absente de la section <VirtualHost>, l'utilisateur du serveur principal sera pris par défaut

Répertoires des utilisateurs :
Avec cette méthode, les requêtes traitées par mod_userdir appelleront le conteneur suEXEC pour exécuter le programme CGI sous l'identifiant utilisateur du répertoire utilisateur concerné. Seuls prérequis pour pouvoir accéder à cette fonctionnalité : l'exécution des CGI doit être activée pour l'utilisateur concerné, et le script doit passer avec succès le test des vérifications de sécurité décrit plus haut. Voir aussi l' option de compilation --with-suexec-userdir.

Débogage de suEXEC

Le conteneur suEXEC va écrire ses informations de journalisation dans le fichier défini par l'option de compilation --with-suexec-logfile comme indiqué plus haut. Si vous pensez avoir configuré et installé correctement le conteneur, consultez ce journal, ainsi que le journal des erreurs du serveur afin de déterminer l'endroit où vous avez fait fausse route.

Avis à la population ! Avertissements et exemples

NOTE ! Cette section est peut-être incomplète. Pour en consulter la dernière révision, voir la version de la Documentation en ligne.

Quelques points importants du conteneur peuvent imposer des contraintes du point de vue de la configuration du serveur. Veuillez en prendre connaissance avant de soumettre un rapport de bogue à propos de suEXEC.

  • Points importants de suEXEC
  • Limitations concernant la hiérarchie.

    Pour des raisons de sécurité et d'efficacité, toutes les requêtes suEXEC ne doivent concerner que des ressources situées dans la racine des documents définie pour les requêtes concernant un hôte virtuel, ou des ressources situées dans la racine des documents définies pour les requêtes concernant un répertoire utilisateur. Par exemple, si vous avez configuré quatre hôtes virtuels, vous devrez définir la structure des racines de documents de vos hôtes virtuels en dehors d'une hiérarchie de documents principale de httpd, afin de tirer parti de suEXEC dans le contexte des hôtes virtuels (Exemple à venir).

  • La variable d'environnement PATH de suEXEC

    Modifier cette variable peut s'avérer dangereux. Assurez-vous que tout chemin que vous ajoutez à cette variable est un répertoire de confiance. Vous n'avez probablement pas l'intention d'ouvrir votre serveur de façon à ce que l'on puisse y exécuter un cheval de Troie.

  • Modification de suEXEC

    Encore une fois, ceci peut vous causer de graves ennuis si vous vous y essayez sans savoir ce que vous faites. Evitez de vous y risquer dans la mesure du possible.


Problèmes liés au DNS avec le serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Problèmes liés au DNS avec le serveur HTTP Apache

Cette page pourrait se résumer ainsi : configurez le serveur HTTP Apache de façon à ce qu'il n'ait pas besoin de résolution DNS pour interpréter les fichiers de configuration. Si httpd doit effectuer des résolutions DNS pour interpréter les fichiers de configuration, votre serveur pourra présenter des problèmes de fiabilité (en d'autres termes, il est possible qu'il refuse de démarrer), ou d'attaques par déni ou usurpation de service (y compris l'attribution de requêtes à un serveur virtuel autre que le serveur virtuel voulu).

Un exemple simple

# Ceci est un exemple de mauvaise configuration ; ne l'utilisez pas comme base
# de configuration
<VirtualHost www.example.dom>
  ServerAdmin webgirl@example.dom
  DocumentRoot "/www/example"
</VirtualHost>

Pour fonctionner correctement, le serveur a absolument besoin de deux informations à propos de chaque serveur virtuel : le nom du serveur défini par la directive ServerName, et au moins une adresse IP à laquelle le serveur va se rattacher et répondre. L'exemple ci-dessus ne comporte pas d'adresse IP, si bien que httpd devra utiliser le DNS pour trouver l'adresse IP de www.example.dom. Si pour une raison quelconque, le DNS n'est pas disponible au moment où votre serveur interprète son fichier de configuration, ce serveur virtuel ne sera pas pris en compte dans la configuration. Il sera incapable de répondre à toute requête pour ce serveur virtuel.

Supposons que l'adresse de www.example.dom soit 192.0.2.1, et examinons cet extrait de configuration :

# Ceci est un exemple de mauvaise configuration ; ne l'utilisez pas comme base
# de configuration
<VirtualHost 192.0.2.1>
  ServerAdmin webgirl@example.dom
  DocumentRoot "/www/example"
</VirtualHost>

Cette fois, httpd doit effectuer une recherche DNS inverse pour trouver le nom ServerName de ce serveur virtuel. Si cette recherche inverse échoue, le serveur virtuel sera partiellement désactivé. Si le serveur virtuel est à base de nom, il sera en fait totalement désactivé, mais s'il est à base d'adresse IP, il fonctionnera probablement. Cependant, httpd échouera s'il doit générer une URL complète pour le serveur qui inclut ce nom de serveur (comme dans le cas d'une redirection).

Voici un extrait de configuration qui permet d'éviter ces deux types de problèmes :

<VirtualHost 192.0.2.1>
  ServerName www.example.dom
  ServerAdmin webgirl@example.dom
  DocumentRoot "/www/example"
</VirtualHost>

Déni de service

Considérons cet extrait de configuration :

<VirtualHost www.example1.dom>
  ServerAdmin webgirl@example1.dom
  DocumentRoot "/www/example1"
</VirtualHost>
<VirtualHost www.example2.dom>
  ServerAdmin webguy@example2.dom
  DocumentRoot "/www/example2"
</VirtualHost>

Supposons que vous ayez assigné 192.0.2.1 à www.example1.dom et 192.0.2.2 à www.example2.dom. En outre, supposons que example1.dom gère son propre DNS. Avec cette configuration, example1.dom sera en mesure de détourner tout trafic destiné à example2.dom. Pour y parvenir, tout ce qu'ils ont à faire consiste à assigner 192.0.2.2 à www.example1.dom. Comme ils gèrent leur propre DNS, vous ne pouvez pas les empêcher de faire pointer l'enregistrement www.example1.dom vers l'adresse qu'ils veulent.

Les requêtes à destination de 192.0.2.2 (y compris toutes celles où l'utilisateur à tapé une URL de la forme http://www.example2.dom/quelquepart), seront toutes servies par le serveur virtuel example1.dom. Une meilleur compréhension de la raison pour laquelle ceci peut se produire nécessite une discussion plus approfondie à propos de la manière dont httpd associe les requêtes entrantes aux différents serveurs virtuels qui vont les servir. Un document de base décrivant ceci est disponible.

L'adresse du "serveur principal"

Le support des serveurs virtuels à base de nom oblige httpd à connaître la/les adresse(s) IP de l'hôte sur lequel httpd s'exécute. Pour obtenir cette adresse, soit il utilise la directive ServerName globale (si elle est présente), soit il fait appel à la fonction C gethostname (qui doit renvoyer le même nom que la commande shell "hostname"). Il effectue ensuite une recherche DNS sur cette adresse. Pour le moment, il n'existe aucun moyen d'éviter cette recherche DNS.

Si vous craignez que cette recherche DNS échoue parce que votre serveur DNS est arrêté, vous pouvez insérer le nom d'hôte dans le fichier /etc/hosts (où il est probablement déjà enregistré afin que la machine démarre correctement). Assurez-vous ensuite que la machine est configurée pour utiliser /etc/hosts dans le cas où la recherche DNS échoue. Suivant le système d'exploitation que vous utilisez, vous y parviendrez en éditant /etc/resolv.conf, ou /etc/nsswitch.conf.

Si votre serveur n'a aucune autre raison d'effectuer des recherches DNS, vous pouvez définir la variable d'environnement HOSTRESORDER à "local", et vous serez alors en mesure d'exécuter httpd. Tout dépend du système d'exploitation et des bibliothèques de résolution de noms que vous utilisez. Elle affecte aussi les programmes CGI, à moins que vous n'utilisiez mod_env pour contrôler l'environnement. Il est conseillé de consulter les pages de manuel ou les FAQs de votre système d'exploitation.

Conseils pour éviter ce genre de problème

  • utilisez des adresses IP au sein des VirtualHost
  • utilisez des adresses IP avec la directive Listen
  • vérifiez que tous les serveurs virtuels possèdent un nom ServerName explicite
  • créez un serveur virtuel <VirtualHost _default_:*> qui n'a aucune page à servir


Documentation sur les serveurs virtuels Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Documentation sur les serveurs virtuels Apache

Le principe des Serveurs Virtuels consiste à faire fonctionner un ou plusieurs serveurs Web (comme www.company1.example.com et www.company2.example.com) sur une même machine. Les serveurs virtuels peuvent être soit "par-IP" où une adresse IP est attribuée pour chaque serveur Web, soit "par-nom" où plusieurs noms de domaine se côtoient sur des mêmes adresses IP. L'utilisateur final ne perçoit pas qu'en fait il s'agit d'un même serveur physique.

Apache a été le précurseur des serveurs proposant cette méthode de serveurs virtuels basés sur les adresses IP. Ses versions 1.1 et suivantes proposent les deux méthodes de serveurs virtuels : par-IP et par-nom. Cette deuxième méthode est parfois également appelée host-based ou serveur virtuel non-IP.

Vous trouverez ci-dessous une liste documentaire qui vous expliquera en détails le fonctionnement du support des serveurs virtuels par le serveur HTTP Apache.

Voir aussi

  • mod_vhost_alias
  • Serveurs virtuels par-nom
  • Serveurs virtuels par-IP
  • Exemples de serveurs virtuels
  • Limites des descripteurs de fichiers
  • Hébergement virtuel en masse
  • Détails sur les critères de choix du serveur

Support des serveurs virtuels

  • Serveurs Virtuels par-Nom (Un ou plusieurs sites Web par adresse IP)
  • Serveurs Virtuels par-IP (Une adresse IP pour chaque site Web)
  • Exemples de configurations classiques de Serveurs Virtuels
  • Limites des descripteurs de fichiers (ou, trop de fichiers journaux)
  • Configuration dynamique en masse de Serveurs Virtuels
  • Explication approfondie des critères de sélection d'un Serveur Virtuel

Directives de configuration

  • <VirtualHost>
  • ServerName
  • ServerAlias
  • ServerPath

Pour vérifier et analyser la configuration de vos serveurs virtuels, vous pouvez utiliser l'argument -S sur la ligne de commande.

Exemple Unix

apachectl -S

Exemple Windows

httpd.exe -S

Cette commande affichera dans le détail comment Apache a traité son fichier de configuration. Les erreurs de configuration peuvent être corrigées par l'examen attentif des adresses IP et des noms de serveurs. (Consultez la documentation du programme httpd pour les autres arguments de la ligne de commande)


Support Apache des serveurs virtuels par nom - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Serveurs virtuels

Support Apache des serveurs virtuels par nom

Ce document décrit quand et comment utiliser des serveurs virtuels par nom.

Voir aussi

  • Support Apache des serveurs virtuels par IP
  • Détails sur le fonctionnement des serveurs virtuels
  • Configuration dynamique des hébergements virtuels de masse
  • Exemples d'utilisations de VirtualHost

Serveurs virtuels par nom vs. par IP

Les serveurs virtuels par IP utilisent l'adresse IP de la connexion afin de déterminer quel serveur virtuel doit répondre. Par conséquent, vous devez disposer d'adresses IP différentes pour chaque serveur.

Avec un hébergement virtuel par nom, le serveur s'appuie sur les informations transmises par le client dans les en-têtes HTTP de ses requêtes. La technique présentée ici vous permet de disposer de serveurs virtuels différents partagés sur une même adresse IP.

L'hébergement virtuel par nom est habituellement plus simple, car il vous suffit de configurer votre serveur DNS pour que chaque domaine pointe sur l'adresse IP dont vous disposez, et de configurer votre serveur Apache HTTP afin qu'il reconnaisse ces domaines. Il réduit aussi la pénurie en adresses IP. Par conséquent, vous devriez utiliser l'hébergement virtuel par nom, sauf dans le cas où vous utiliseriez des équipements qui nécessitent un hébergement basé sur IP. Les raisons historiques de l'hébergement basé sur IP dans un but de support de certains clients ne s'appliquent plus à un serveur web d'usage général.

La sélection du serveur virtuel en fonction du nom s'opère en dehors de l'algorithme de sélection du serveur virtuel en fonction de l'adresse IP, ce qui signifie que les recherches du point de vue du nom du serveur ne s'effectuent que parmi le jeu de serveurs virtuels pour lesquels la correspondance avec la paire adresse IP/port est la plus exacte.

Comment le serveur sélectionne-t-il le serveur virtuel basé sur le nom approprié

Il est important de savoir que la première étape de la résolution de serveur virtuel basée sur le nom est une résolution basée sur IP. La résolution de serveur virtuel basée sur le nom ne fait que choisir le serveur virtuel basé sur le nom le plus approprié, en se limitant aux candidats qui conviennent le mieux du point de vue IP. La résolution basée sur IP est sans objet si l'on utilise un caractère générique (*) pour l'adresse IP dans toutes les directives VirtualHost.

A l'arrivée d'une requête, le serveur va rechercher l'argument de section <VirtualHost> présentant la meilleure (la plus exacte) correspondance avec la paire adresse IP/port utilisée dans la requête. Si plusieurs serveurs virtuels possèdent cette même paire adresse IP/port, Apache va ensuite comparer les valeurs des directives ServerName et ServerAlias avec le nom de serveur présent dans la requête.

Si vous ne définissez pas de directive ServerName pour un serveur virtuel à base de nom, le serveur utilisera par défaut le nom de domaine entièrement qualifié (FQDN) déduit du nom d'hôte système. Cette configuration sans nom de serveur explicite peut conduire à des erreurs de choix du serveur virtuel à utiliser et est déconseillée.

Le serveur virtuel à base de nom par défaut pour une paire adresse IP/port

Si aucune directive ServerName ou ServerAlias ne correspond dans la liste de serveurs virtuels présentant la meilleure correspondance du point de vue adresse IP/port, c'est le premier serveur virtuel de cette liste qui sera utilisé.

Utilisation de serveurs virtuels par nom

Modules Apparentés Directives Apparentées
  • core
  • DocumentRoot
  • ServerAlias
  • ServerName
  • <VirtualHost>

La première étape consiste à créer une section <VirtualHost> pour chacun des serveurs à définir. Dans chaque section <VirtualHost>, vous devez définir au minimum une directive ServerName pour désigner le serveur concerné et une directive DocumentRoot pour préciser l'emplacement sur le système de fichiers du contenu de ce serveur.

Le serveur principal disparaît

Toute requête qui ne correspond à aucune section <VirtualHost> existante est traitée avec la configuration du serveur principal, sans tenir compte du nom d'hôte ou de la directive ServerName.

Lorsque vous ajoutez un serveur virtuel basé sur le nom à un serveur existant, et si les caractéristiques de ce serveur virtuel correspondent à des combinaisons IP/port préexistantes, les requêtes seront alors traitées par un serveur virtuel explicite. Dans ce cas, il est en général judicieux de créer un serveur virtuel par défaut comportant une directive ServerName correspondant au nom du serveur principal. De nouveaux domaines sur les mêmes interface et port, mais nécessitant des configurations distinctes, pourront alors être ajoutés en tant que serveurs virtuels spécifiques (et non par défaut).

Héritage du nom de serveur

Il est toujours préférable de définir une directive ServerName au niveau de chaque serveur virtuel à base de nom. Si un serveur virtuel ne définit pas de directive ServerName, le nom de ce serveur virtuel sera hérité du serveur principal. Si aucun nom de serveur n'a été explicitement défini au niveau du serveur principal, le serveur tentera de déterminer son nom via une résolution de nom DNS inverse sur la première adresse d'écoute. Dans tous les cas, ce nom de serveur hérité influencera la sélection du serveur virtuel à base de nom, c'est pourquoi il est toujours préférable de définir une directive ServerName pour chaque serveur virtuel à base de nom.

Par exemple, supposez que vous hébergez le domaine www.example.com et que vous souhaitez ajouter le serveur virtuel other.example.com qui pointe sur la même adresse IP. Il vous suffit d'ajouter la configuration suivante à httpd.conf :

<VirtualHost *:80>
    # Le premier serveur virtuel de la liste est aussi le
    # serveur par défaut pour *:80
    ServerName www.example.com
    ServerAlias example.com
    DocumentRoot "/www/domain"
</VirtualHost>

<VirtualHost *:80>
    ServerName other.example.com
    DocumentRoot "/www/otherdomain"
</VirtualHost>

Autrement, vous pouvez spécifiez une adresse IP explicite à la place de * dans la directive <VirtualHost>. Par exemple, cette méthode est utile si vous souhaitez faire tourner quelques serveurs virtuels par nom sur une même adresse IP, et d'autres, soit par IP, soit basés sur un autre jeu de serveurs virtuels par nom sur une autre adresse IP.

Plusieurs serveurs sont accessibles par plus d'un nom. Il suffit de placer la directive ServerAlias dans une section <VirtualHost>. Par exemple, dans la première section <VirtualHost> ci-dessus, la directive ServerAlias indique aux utilisateurs les autres noms permis pour accéder au même site Web :

ServerAlias example.com *.example.com

ainsi, toutes les requêtes portant sur un domaine example.com seront servies par le serveur virtuel www.example.com. Les caractères joker * et ? peuvent être utilisés pour les correspondances. Bien entendu, vous ne pouvez pas inventer des noms et les placer dans une directive ServerName ou ServerAlias. Tout d'abord, votre serveur DNS doit être correctement configuré pour lier ces noms à une adresse IP associée avec votre serveur.

La recherche du serveur virtuel à base de nom qui correspond au plus près à la requête s'effectue parmi les <virtualhost> selon leur ordre d'apparition dans le fichier de configuration. Le premier serveur virtuel dont le ServerName ou le ServerAlias correspond est utilisé, sans priorité particulière en cas de présence de caractères génériques (que ce soit pour le ServerName ou le ServerAlias).

La liste complète des noms dans la section VirtualHost sont traités comme une directive ServerAlias sans caractères génériques.

Finalement, vous pouvez affiner la configuration des serveurs virtuels en plaçant d'autres directives à l'intérieur des sections <VirtualHost>. La plupart des directives peut être placée dans ces sections en y changeant seulement la configuration du serveur virtuel associé. Pour déterminer si une directive particulière est permise, consultez le contexte de la directive. Le jeu de directives configurées dans le contexte du serveur principal (en dehors de toutes sections <VirtualHost>) sera utilisé seulement s'il n'y a pas de configuration contraire par un serveur virtuel.


Support Apache des serveurs virtuels par IP - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Serveurs virtuels

Support Apache des serveurs virtuels par IP

Voir aussi

  • Support Apache des serveurs virtuels par nom

Système requis

Comme l'indique le terme par IP, le serveur doit disposer de différentes paires adresses IP/port pour chaque serveur virtuel par IP. La machine peut posséder plusieurs connexions physiques au réseau, ou utiliser des interfaces virtuelles qui sont supportées par la plupart des systèmes d'exploitation modernes (Consultez la documentation des systèmes d'exploitation pour plus de détails, notamment les "alias IP" et la commande "ifconfig" pour les activer), et/ou utiliser plusieurs numéros de port.

Selon la terminologie du serveur HTTP Apache, l'utilisation d'une seule adresse IP avec plusieurs ports TCP s'apparente aussi à de l'hébergement virtuel basé sur IP.

Comment configurer Apache

Il y a deux manières de configurer Apache pour le support de multiples serveurs virtuels. Il suffit soit de faire tourner un processus résident httpd pour chaque nom de domaine, soit de faire tourner un unique processus résident qui gère tous les serveurs virtuels.

Utilisez des processus résidents multiples lorsque :

  • il y a des problèmes de répartition de sécurité, tels qu'une entreprise1 ne souhaite que personne d'une entreprise2 ne puisse lire ses données excepté via le Web. Dans ce cas, vous aurez besoin de deux processus résidents, chacun fonctionnant avec des paramètres User, Group, Listen, et ServerRoot différents.
  • vous disposez suffisamment de mémoire et de descripteurs de fichiers pour l'écoute de chaque alias IP de la machine. Il est seulement possible d'appliquer la directive Listen, soit sur toutes les adresses avec le joker "*", soit uniquement sur des adresses spécifiques. Donc, si vous avez besoin d'écouter une adresse en particulier, vous devrez le faire pour l'ensemble des autres adresses (Bien qu'il soit plus simple de lancer un processus httpd pour écouter N-1 adresses, et un autre pour l'adresse restante).

Utilisez un unique processus résident lorsque :

  • le partage de la configuration httpd entre les serveurs virtuels est acceptable.
  • la machine assume déjà une grande quantité de requêtes, et que l'ajout de processus résidents supplémentaires en affecterait les performances.

Configuration de processus multiples

Créez une installation indépendante du programme httpd pour chaque serveur virtuel. Pour chacune d'elle, utilisez la directive Listen dans le fichier de configuration pour définir l'adresse IP (ou serveur virtuel) que le processus résident doit gérer. Par exemple :

Listen 192.0.2.100:80

Il est recommandé d'utiliser une adresse IP plutôt qu'un nom de domaine (consultez Problèmes DNS avec Apache).

Configuration d'un unique processus résident pour des serveurs virtuels

Dans ce cas, un unique processus httpd va gérer les requêtes pour le serveur principal et tous les serveurs virtuels. Dans le fichier de configuration, la directive VirtualHost va servir à définir les autres directives ServerAdmin, ServerName, DocumentRoot, ErrorLog et TransferLog ou CustomLog avec des valeurs différentes pour chaque serveur virtuel. Par exemple :

<VirtualHost 172.20.30.40:80>
    ServerAdmin webmaster@www1.example.com
    DocumentRoot "/www/vhosts/www1"
    ServerName www1.example.com
    ErrorLog "/www/logs/www1/error_log"
    CustomLog "/www/logs/www1/access_log" combined
</VirtualHost>

<VirtualHost 172.20.30.50:80>
    ServerAdmin webmaster@www2.example.org
    DocumentRoot "/www/vhosts/www2"
    ServerName www2.example.org
    ErrorLog "/www/logs/www2/error_log"
    CustomLog "/www/logs/www2/access_log" combined
</VirtualHost>

Il est recommandé d'utiliser une adresse IP plutôt qu'un nom de domaine comme argument à la directive <VirtualHost> (consultez Problèmes DNS avec Apache).

Presque toutes les directives de configuration peuvent être employées dans une directive VirtualHost, à l'exception des directives qui contrôlent la création du processus et de quelques autres. Pour connaître celles utilisables dans une directive VirtualHost, vérifiez leur Contexte en utilisant l'directive index.

SuexecUserGroup peut être utilisées à l'intérieur d'une directive VirtualHost si l'exécution se fait sous suEXEC. (Voir suEXEC).

SÉCURITÉ : lorsque vous spécifiez où écrire les fichiers journaux, soyez attentif aux risques si quelqu'un d'autre que celui qui a démarré Apache dispose des droits d'écriture sur l'emplacement de ces fichiers. Consultez les Conseils sur la sécurité pour plus de détails.


Hébergement virtuel de masse configuré dynamiquement - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Hébergement virtuel

Hébergement virtuel de masse configuré dynamiquement

Ce document propose une méthode performante pour servir un nombre quelconque d'hôtes virtuels avec le serveur HTTP Apache. Un document séparé décrit comment utiliser mod_rewrite pour gérer l'hébergement virtuel de masse dynamique.

A qui ce document est-il destiné ?

Les techniques décrites ici vous concernent si votre httpd.conf contient de nombreuses sections <VirtualHost> très semblables, dans le style :

<VirtualHost 111.22.33.44>
    ServerName                 customer-1.example.com
    DocumentRoot        "/www/hosts/customer-1.example.com/docs"
    ScriptAlias  "/cgi-bin/" "/www/hosts/customer-1.example.com/cgi-bin"
</VirtualHost>

<VirtualHost 111.22.33.44>
    ServerName                 customer-2.example.com
    DocumentRoot        "/www/hosts/customer-2.example.com/docs"
    ScriptAlias  "/cgi-bin/" "/www/hosts/customer-2.example.com/cgi-bin"
</VirtualHost>

<VirtualHost 111.22.33.44>
    ServerName                 customer-N.example.com
    DocumentRoot        "/www/hosts/customer-N.example.com/docs"
    ScriptAlias  "/cgi-bin/" "/www/hosts/customer-N.example.com/cgi-bin"
</VirtualHost>

Nous voulons remplacer toutes les configurations <VirtualHost> par un mécanisme qui les génère dynamiquement. Ceci présente certains avantages :

  1. Votre fichier de configuration est plus petit, ainsi Apache démarre plus rapidement et consomme moins de mémoire. Et ce qui est peut-être le plus important, le fichier de configuration plus petit est plus facile à maintenir, et le risque d'erreurs en est diminué d'autant.
  2. Pour ajouter des serveurs virtuels, il suffit de créer les répertoires appropriés dans le système de fichiers et les entrées dans le DNS - il n'est plus nécessaire de reconfigurer ou de redémarrer Apache.

Le principal désavantage réside dans le fait que vous ne pouvez pas définir un fichier journal différent pour chaque serveur virtuel. De toute façon, ce serait une mauvaise idée si vous avez de nombreux serveurs virtuels, car cela nécessiterait un nombre important de descripteurs de fichier. Il est préférable de rediriger les journaux via un pipe ou une file fifo vers un programme, et faire en sorte que ce dernier éclate les journaux en un journal par serveur virtuel. L'utilitaire split-logfile constitue un exemple de ce traitement.

Vue d'ensemble

Un serveur virtuel peut être défini par deux informations : son adresse IP, et le contenu de l'en-tête Host: de la requête HTTP. La technique d'hébergement virtuel dynamique de masse utilisée ici consiste à insérer automatiquement ces informations dans le chemin du fichier à utiliser pour répondre à la requête. On peut y parvenir assez facilement en utilisant mod_vhost_alias avec Apache httpd, mais on peut aussi utiliser mod_rewrite.

Par défaut, ces deux modules sont désactivés ; vous devez activer l'un d'eux lors de la compilation et de la configuration d'Apache httpd si vous voulez utiliser cette technique.

Certains paramètres doivent être extraits de la requête pour que le serveur dynamique se présente comme un serveur dynamique normal. Le plus important est le nom du serveur, que le serveur utilise pour générer des URLs d'auto-référencement, etc... Il est défini via la directive ServerName, et les CGIs peuvent s'y référer via la variable d'environnement SERVER_NAME. Sa véritable valeur utilisée à l'exécution est contrôlée par la définition de la directive UseCanonicalName. Avec UseCanonicalName Off, le nom du serveur correspond au contenu de l'en-tête Host: de la requête. Avec UseCanonicalName DNS, il est extrait d'une recherche DNS inverse sur l'adresse IP du serveur virtuel. La première configuration est utilisée pour l'hébergement virtuel dynamique par nom, et la deuxième pour l'hébergement virtuel dynamique par IP. Si httpd ne peut pas déterminer le nom du serveur, soit parce qu'il n'y a pas d'en-tête Host:, soit parce que la recherche DNS a échoué, il prend en compte la valeur définie par la directive ServerName.

L'autre paramètre à extraire est la racine des documents (définie via la directive DocumentRoot et disponible pour les scripts CGI via la variable d'environnement DOCUMENT_ROOT). Dans une configuration classique, il est utilisé par le module core pour faire correspondre les URIs aux noms de fichiers, mais lorsque la configuration du serveur comporte des serveurs virtuels, ce traitement doit être pris en charge par un autre module (soit mod_vhost_alias, soit mod_rewrite), qui utilise un méthode de correspondance différente. Aucun de ces modules ne se chargeant de définir la variable d'environnement DOCUMENT_ROOT, si des CGIs ou des documents SSI doivent en faire usage, ils obtiendront une valeur erronée.

Hébergement virtuel dynamique avec mod_vhost_alias

Cet extrait de fichier httpd.conf implémente l'hébergement virtuel décrit dans la section À qui ce document est-il destiné ? ci-dessus en utilisant mod_vhost_alias.

# extrait le nom du serveur de l'en-tête Host:
UseCanonicalName Off

# ce format de journal peut être éclaté en journaux par serveur virtuel
# à l'aide du premier champ via l'utilitaire split-logfile
LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
CustomLog "logs/access_log" vcommon

# inclut le nom du serveur dans les noms de fichiers ressources
# nécessaires aux traitements des requêtes
VirtualDocumentRoot "/www/hosts/%0/docs"
VirtualScriptAlias  "/www/hosts/%0/cgi-bin"

Pour changer cette configuration en solution de serveur virtuel par IP, il suffit de remplacer UseCanonicalName Off par UseCanonicalName DNS. Le nom du serveur inséré dans le nom de fichier sera alors déduit de l'adresse IP du serveur virtuel. La variable %0 fait référence au nom de serveur de la requête, tel qu'il est indiqué dans l'en-tête Host:.

Voir la documentation du module mod_vhost_alias pour d'avantages d'exemples d'utilisation.

Système de serveurs virtuels dynamiques simplifié

Il s'agit d'une adaptation du système ci-dessus, ajusté pour un serveur d'hébergement web de FAI. Grâce à la variable %2, on peut extraire des sous-chaînes de caractères du nom du serveur pour les utiliser dans le nom de fichier afin, par exemple, de définir /home/user/www comme emplacement des documents pour www.user.example.com. Un seul répertoire cgi-bin suffit pour l'ensemble des serveurs virtuels.

UseCanonicalName Off

LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
CustomLog "logs/access_log" vcommon

# insertion d'une partie du nom du serveur dans les noms de fichiers
VirtualDocumentRoot "/home/%2/www"

# répertoire cgi-bin unique
ScriptAlias  "/cgi-bin/"  "/www/std-cgi/"

Vous trouverez des exemples plus élaborés d'utilisation de la directive VirtualDocumentRoot dans la documentation du module mod_vhost_alias.

Utiliser plusieurs systèmes d'hébergement virtuel sur le même serveur

Moyennant une configuration un peu plus compliquée, vous pouvez contrôler la portée des différentes configurations d'hébergement virtuel à l'aide des directives <VirtualHost> normales de httpd. Par exemple, on peut associer une adresse IP pour les pages d'accueil des clients en général, et une autre pour les clients commerciaux avec la configuration suivante. Cette configuration peut être combinée avec les sections <VirtualHost> conventionnelles, comme indiqué plus loin.

UseCanonicalName Off

LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon

<Directory "/www/commercial">
    Options FollowSymLinks
    AllowOverride All
</Directory>

<Directory "/www/homepages">
    Options FollowSymLinks
    AllowOverride None
</Directory>

<VirtualHost 111.22.33.44>
    ServerName www.commercial.example.com

    CustomLog "logs/access_log.commercial" vcommon

    VirtualDocumentRoot "/www/commercial/%0/docs"
    VirtualScriptAlias  "/www/commercial/%0/cgi-bin"
</VirtualHost>

<VirtualHost 111.22.33.45>
    ServerName www.homepages.example.com

    CustomLog "logs/access_log.homepages" vcommon

    VirtualDocumentRoot "/www/homepages/%0/docs"
    ScriptAlias         "/cgi-bin/" "/www/std-cgi/"
</VirtualHost>

Note

Si le premier bloc VirtualHost ne comporte pas de directive ServerName, c'est le nom issu d'une recherche DNS inverse à partir de l'adresse IP du serveur virtuel qui sera utilisé. Si ce nom ne correspond pas à celui que vous voulez utiliser, vous pouvez ajouter une entrée de remplacement (par exemple ServerName none.example.com) pour éviter ce comportement.

Pour un hébergement virtuel par IP plus efficace

Les changements de configuration suggérés pour transformer le premier exemple en hébergement virtuel par IP conduisent à une configuration peu efficace. Chaque requête nécessite une nouvelle recherche DNS. Pour éviter cette surcharge de travail, le système de fichiers peut être organisé pour correspondre aux adresses IP, plutôt qu'aux noms de serveurs, supprimant par la-même la nécessité d'une recherche DNS. La journalisation doit aussi être adaptée pour fonctionner sur un tel système.

# obtention du nom du serveur par recherche DNS inverse
# sur l'adresse IP
UseCanonicalName DNS

# insertion de l'adresse IP dans les journaux afin de pouvoir les
# éclater
LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon
CustomLog "logs/access_log" vcommon

# insertion de l'adresse IP dans les noms de fichiers
VirtualDocumentRootIP "/www/hosts/%0/docs"
VirtualScriptAliasIP  "/www/hosts/%0/cgi-bin"

Hébergement virtuel de masse avec mod_rewrite

L'hébergement virtuel de masse peut aussi être effectué en utilisant mod_rewrite, soit à l'aide de simples directives RewriteRule, soit en utilisant des techniques plus compliquées comme le stockage externe des définitions des serveurs virtuels, ces dernières étant accessibles via des directives RewriteMap. Ces techniques sont décrites dans la documentation sur la réécriture.

Hébergement virtuel en masse avec mod_macro

Une autre option pour générer dynamiquement des serveurs virtuels : mod_macro ; ce module permet de créer un modèle de serveur virtuel que vous pourrez invoquer pour des noms d'hôtes multiples. La section Usage de la documentation du module présente un exemple qui illustre cette méthode.


Exemples d'utilisations de VirtualHost - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Serveurs virtuels

Exemples d'utilisations de VirtualHost

Le but de ce document est d'essayer de répondre aux questions les plus répandues sur la configuration des serveurs virtuels. Les scénarios présentés ici se rencontrent quand plusieurs serveurs Webs doivent tourner sur une seule et même machine au moyen de serveurs virtuels par nom ou par IP.

Fonctionnement de plusieurs serveurs virtuels par nom sur une seule adresse IP.

Votre serveur possède plusieurs noms d'hôte qui correspondent à une seule adresse IP, et vous souhaitez des réponses différentes si on demande www.example.com ou www.example.org.

Note :

La configuration de serveurs virtuels sous Apache ne provoque pas leur apparition magique dans la configuration du DNS. Il faut que leurs noms soient définis dans le DNS, et qu'ils y soient résolus sur l'adresse IP du serveur, faute de quoi personne ne pourra visiter votre site Web. Il est possible d'ajouter des entrées dans le fichier hosts pour tests locaux, mais qui ne fonctionneront que sur la machine possédant ces entrées.

# Apache doit écouter sur le port 80
Listen 80
<VirtualHost *:80>
    DocumentRoot "/www/example1"
    ServerName www.example.com

    # Autres directives ici
</VirtualHost>

<VirtualHost *:80>
    DocumentRoot "/www/example2"
    ServerName www.example.org

    # Autres directives ici
</VirtualHost>

Les astérisques correspondent à toutes les adresses, si bien que le serveur principal ne répondra jamais à aucune requête. Comme le serveur virtuel ServerName www.example.com se trouve en premier dans le fichier de configuration, il a la plus grande priorité et peut être vu comme serveur par défaut ou primaire ; ce qui signifie que toute requête reçue ne correspondant à aucune des directives ServerName sera servie par ce premier <VirtualHost>.

La configuration ci-dessus correspond à ce que l'on souhaite pour la plupart des serveurs virtuels à base de nom. Il faudra cependant utiliser une configuration différente si vous souhaitez servir un contenu différent en fonction de l'adresse IP ou du port.

Note :

Vous pouvez remplacer * par une adresse IP du système. Le serveur virtuel concerné ne sera alors sélectionné que pour les requêtes HTTP vers cette adresse IP.

En général, il est commode d'utiliser * sur les systèmes dont l'adresse IP n'est pas constante - par exemple, pour des serveurs dont l'adresse IP est attribuée dynamiquement par le FAI, et où le DNS est géré au moyen d'un DNS dynamique quelconque. Comme * signifie n'importe quelle adresse, cette configuration fonctionne sans devoir être modifiée quand l'adresse IP du système est modifiée.

Serveurs virtuels par nom sur plus d'une seule adresse IP.

Note :

Toutes les techniques présentées ici peuvent être étendues à un plus grand nombre d'adresses IP.

Le serveur a deux adresses IP. Sur l'une (172.20.30.40), le serveur "principal" server.example.com doit répondre, et sur l'autre (172.20.30.50), deux serveurs virtuels (ou plus) répondront.

Listen 80

# Serveur "principal" sur 172.20.30.40
ServerName server.example.com
DocumentRoot "/www/mainserver"

<VirtualHost 172.20.30.50>
    DocumentRoot "/www/example1"
    ServerName www.example.com

    # D'autres directives ici ...
</VirtualHost>

<VirtualHost 172.20.30.50>
    DocumentRoot "/www/example2"
    ServerName www.example.org

    # D'autres directives ici ...
</VirtualHost>

Toute requête arrivant sur une autre adresse que 172.20.30.50 sera servie par le serveur principal. Les requêtes vers 172.20.30.50 avec un nom de serveur inconnu, ou sans en-tête Host:, seront servies par www.example.com.

Servir le même contenu sur des adresses IP différentes (telle qu'une adresse interne et une externe).

La machine serveur dispose de deux adresses IP (192.168.1.1 et 172.20.30.40). Cette machine est placée à la fois sur le réseau interne (l'Intranet) et le réseau externe (Internet). Sur Internet, le nom server.example.com pointe vers l'adresse externe (172.20.30.40), mais sur le réseau interne, ce même nom pointe vers l'adresse interne (192.168.1.1).

Le serveur peut être configuré pour répondre de la même manière aux requêtes internes et externes, au moyen d'une seule section <VirtualHost>.

<VirtualHost 192.168.1.1 172.20.30.40>
    DocumentRoot "/www/server1"
    ServerName server.example.com
    ServerAlias server
</VirtualHost>

Ainsi, les requêtes en provenance de chacun des deux réseaux seront servies par le même <VirtualHost>.

Note :

Sur le réseau interne, il est possible d'utiliser le nom raccourci server au lieu du nom complet server.example.com.

Notez également que dans l'exemple précédent, vous pouvez remplacer la liste des adresses IP par des * afin que le serveur réponde de la même manière sur toutes ses adresses.

Servir différents sites sur différents ports.

Vous disposez de plusieurs domaines pointant sur la même adresse IP et vous voulez également servir de multiples ports. L'exemple suivant montre que la sélection en fonction du nom intervient après la sélection de la meilleure correspondance du point de vue adresse IP/port.

Listen 80
Listen 8080

<VirtualHost 172.20.30.40:80>
    ServerName www.example.com
    DocumentRoot "/www/domain-80"
</VirtualHost>

<VirtualHost 172.20.30.40:8080>
    ServerName www.example.com
    DocumentRoot "/www/domain-8080"
</VirtualHost>

<VirtualHost 172.20.30.40:80>
    ServerName www.example.org
    DocumentRoot "/www/otherdomain-80"
</VirtualHost>

<VirtualHost 172.20.30.40:8080>
    ServerName www.example.org
    DocumentRoot "/www/otherdomain-8080"
</VirtualHost>

Hébergement virtuel basé sur IP

Le serveur dispose de deux adresses IP (172.20.30.40 et 172.20.30.50) correspondant respectivement aux noms www.example.com et www.example.org.

Listen 80

<VirtualHost 172.20.30.40>
    DocumentRoot "/www/example1"
    ServerName www.example.com
</VirtualHost>

<VirtualHost 172.20.30.50>
    DocumentRoot "/www/example2"
    ServerName www.example.org
</VirtualHost>

Les requêtes provenant d'adresses non spécifiées dans l'une des directives <VirtualHost> (comme pour localhost par exemple) seront dirigées vers le serveur principal, s'il en existe un.

Hébergements virtuels mixtes basés sur les ports et sur les IP

Le serveur dispose de deux adresses IP (172.20.30.40 et 172.20.30.50) correspondant respectivement aux noms www.example.com et www.example.org. Pour chacun d'eux, nous voulons un hébergement sur les ports 80 et 8080.

Listen 172.20.30.40:80
Listen 172.20.30.40:8080
Listen 172.20.30.50:80
Listen 172.20.30.50:8080

<VirtualHost 172.20.30.40:80>
    DocumentRoot "/www/example1-80"
    ServerName www.example.com
</VirtualHost>

<VirtualHost 172.20.30.40:8080>
    DocumentRoot "/www/example1-8080"
    ServerName www.example.com
</VirtualHost>

<VirtualHost 172.20.30.50:80>
    DocumentRoot "/www/example2-80"
    ServerName www.example.org
</VirtualHost>

<VirtualHost 172.20.30.50:8080>
    DocumentRoot "/www/example2-8080"
    ServerName www.example.org
</VirtualHost>

Hébergements virtuels mixtes basé sur les noms et sur IP

Toute adresse indiquée comme argument d'une section VirtualHost et n'apparaissant dans aucun autre serveur virtuel, fait de cette section un serveur virtuel sélectionnable uniquement en fonction de son adresse IP.

Listen 80
<VirtualHost 172.20.30.40>
    DocumentRoot "/www/example1"
    ServerName www.example.com
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/www/example2"
    ServerName www.example.org
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/www/example3"
    ServerName www.example.net
</VirtualHost>

# IP-based
<VirtualHost 172.20.30.50>
    DocumentRoot "/www/example4"
    ServerName www.example.edu
</VirtualHost>

<VirtualHost 172.20.30.60>
    DocumentRoot "/www/example5"
    ServerName www.example.gov
</VirtualHost>

Utilisation simultanée de Virtual_host et de mod_proxy

L'exemple suivant montre comment une machine peut mandater un serveur virtuel fonctionnant sur le serveur d'une autre machine. Dans cet exemple, un serveur virtuel de même nom est configuré sur une machine à l'adresse 192.168.111.2. La directive ProxyPreserveHost On est employée pour permette au nom de domaine d'être préservé lors du transfert, au cas où plusieurs noms de domaines cohabitent sur une même machine.

<VirtualHost *:*>
    ProxyPreserveHost On
    ProxyPass        "/" "http://192.168.111.2/"
    ProxyPassReverse "/" "http://192.168.111.2/"
    ServerName hostname.example.com
</VirtualHost>

Utilisation de serveurs virtuels _default_

Serveurs virtuels _default_ pour tous les ports

Exemple de capture de toutes les requêtes émanant d'adresses IP ou de ports non connus, c'est-à-dire, d'un couple adresse/port non traité par aucun autre serveur virtuel.

<VirtualHost _default_:*>
    DocumentRoot "/www/default"
</VirtualHost>

L'utilisation d'un tel serveur virtuel avec un joker pour le port empêche de manière efficace qu'une requête n'atteigne le serveur principal.

Un serveur virtuel par défaut ne servira jamais une requête qui est envoyée vers un couple adresse/port utilisée par un serveur virtuel par nom. Si la requête contient un en-tête Host: inconnu, ou si celui-ci est absent, elle sera toujours servie par le serveur virtuel primaire par nom (celui correspondant à ce couple adresse/port trouvé en premier dans le fichier de configuration).

Vous pouvez utiliser une directive AliasMatch ou RewriteRule afin de réécrire une requête pour une unique page d'information (ou pour un script).

Serveurs virtuels _default_ pour des ports différents

La configuration est similaire à l'exemple précédent, mais le serveur écoute sur plusieurs ports et un second serveur virtuel _default_ pour le port 80 est ajouté.

<VirtualHost _default_:80>
    DocumentRoot "/www/default80"
    # ...
</VirtualHost>

<VirtualHost _default_:*>
    DocumentRoot "/www/default"
    # ...
</VirtualHost>

Le serveur virtuel par défaut défini pour le port 80 (il doit impérativement être placé avant un autre serveur virtuel par défaut traitant tous les ports grâce au joker *) capture toutes les requêtes envoyées sur une adresse IP non spécifiée. Le serveur principal n'est jamais utilisé pour servir une requête.

Serveurs virtuels _default_ pour un seul port

Nous voulons créer un serveur virtuel par défaut seulement pour le port 80.

<VirtualHost _default_:80>
    DocumentRoot "/www/default"
...
</VirtualHost>

Une requête vers une adresse non spécifiée sur le port 80 sera servie par le serveur virtuel par défaut, et toute autre requête vers une adresse et un port non spécifiés sera servie par le serveur principal.

L'utilisation du caractère générique * dans la déclaration d'un serveur virtuel l'emporte sur _default_.

Migration d'un serveur virtuel par nom en un serveur virtuel par IP

Le serveur virtuel par nom avec le nom de domaine www.example.org (de notre exemple par nom) devrait obtenir sa propre adresse IP. Pendant la phase de migration, il est possible d'éviter les problèmes avec les noms de serveurs et autres serveurs mandataires qui mémorisent les vielles adresses IP pour les serveurs virtuels par nom.
La solution est simple, car il suffit d'ajouter la nouvelle adresse IP (172.20.30.50) dans la directive VirtualHost.

Listen 80
ServerName www.example.com
DocumentRoot "/www/example1"

<VirtualHost 172.20.30.40 172.20.30.50>
    DocumentRoot "/www/example2"
    ServerName www.example.org
    # ...
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/www/example3"
    ServerName www.example.net
    ServerAlias *.example.net
    # ...
</VirtualHost>

Le serveur virtuel peut maintenant être joint par la nouvelle adresse (comme un serveur virtuel par IP) et par l'ancienne adresse (comme un serveur virtuel par nom).

Utilisation de la directive ServerPath

Dans le cas où vous disposez de deux serveurs virtuels par nom, le client doit transmettre un en-tête Host: correct pour déterminer le serveur concerné. Les vieux clients HTTP/1.0 n'envoient pas un tel en-tête et Apache n'a aucun indice pour connaître le serveur virtuel devant être joint (il sert la requête à partir d'un serveur virtuel primaire). Dans un soucis de préserver la compatibilité descendante, il suffit de créer un serveur virtuel primaire chargé de retourner une page contenant des liens dont les URLs auront un préfixe identifiant les serveurs virtuels par nom.

<VirtualHost 172.20.30.40>
    # serveur virtuel primaire
    DocumentRoot "/www/subdomain"
    RewriteEngine On
    RewriteRule "." "/www/subdomain/index.html"
    # ...
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/www/subdomain/sub1"
    ServerName www.sub1.domain.tld
    ServerPath "/sub1/"
    RewriteEngine On
    RewriteRule "^(/sub1/.*)" "/www/subdomain$1
    # ...
</VirtualHost>

<VirtualHost 172.20.30.40>
    DocumentRoot "/www/subdomain/sub2"
    ServerName www.sub2.domain.tld
    ServerPath "/sub2/"
    RewriteEngine On
    RewriteRule "^(/sub2/.*)" "/www/subdomain$1"
    # ...
</VirtualHost>

À cause de la directive ServerPath, une requête sur une URL http://www.sub1.domain.tld/sub1/ est toujours servie par le serveur sub1-vhost.
Une requête sur une URL http://www.sub1.domain.tld/ n'est servie par le serveur sub1-vhost que si le client envoie un en-tête Host: correct. Si aucun en-tête Host: n'est transmis, le serveur primaire sera utilisé.

Notez qu'il y a une singularité : une requête sur http://www.sub2.domain.tld/sub1/ est également servie par le serveur sub1-vhost si le client n'envoie pas d'en-tête Host:.

Les directives RewriteRule sont employées pour s'assurer que le client qui envoie un en-tête Host: correct puisse utiliser d'autres variantes d'URLs, c'est-à-dire avec ou sans préfixe d'URL.


Détails sur le fonctionnement des serveurs virtuels - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Serveurs virtuels

Détails sur le fonctionnement des serveurs virtuels

Ce document vise à expliquer dans le détail comment le serveur HTTP Apache procède lors du choix de l'utilisation d'un serveur virtuel en fonction d'une requête reçue.

Il est recommandé de lire la documentation Serveurs virtuels à base de nom et serveurs virtuels à base d'adresse IP pour déterminer quel type de serveur virtuel nous convient le mieux, puis de lire les documentations serveurs virtuels à base de nom ou serveurs virtuels à base d'adresse IP, et enfin d'étudier quelques exemples.

Si vous voulez entrer dans les détails, vous pouvez revenir vers cette page.

Voir aussi

  • Support des serveurs virtuels à base d'adresse IP
  • Support des serveurs virtuels à base de nom
  • Exemples de serveurs virtuels pour une configuration courante
  • Hébergement virtuel de masse configuré dynamiquement

Fichier de configuration

Un serveur principal (main_server) contient toutes les définitions qui apparaissent en dehors des sections <VirtualHost>.

Les serveurs virtuels, aussi appelés vhosts (pour virtual hosts), sont définis par les sections <VirtualHost>.

Chaque directive VirtualHost comporte une ou plusieurs adresses et des ports optionnels.

Il est possible d'utiliser des noms d'hôtes dans la définition d'un serveur virtuel, mais ils seront résolus en adresses IP au démarrage du serveur, et si une résolution de nom échoue, cette définition de serveur virtuel sera ignorée. Cette méthode est par conséquent déconseillée.

L'adresse peut être spécifiée sous la forme *, ce qui conviendra à la requête si aucun autre serveur virtuel ne possède l'adresse IP explicite correspondant à celle de la requête.

L'adresse qui apparaît dans la directive VirtualHost peut être associée à un port optionnel. Si aucun port n'est spécifié, il s'agit d'un port générique qui peut aussi être spécifié comme *. Le port générique correspond à toutes les valeurs de port.

(Il ne faut pas confondre les numéros de port sur lesquels Apache est en écoute avec les numéros de port spécifiés dans la directive VirtualHost ; ces derniers ne servent qu'à définir le serveur virtuel qui sera sélectionné pour traiter la requête. Pour définir les ports sur lesquels Apache est en écoute, utilisez la directive Listen).

L'ensemble des adresses (y compris les résultats multiples A issus des requêtes DNS) est appelé jeu d'adresses du serveur virtuel.

Apache fait automatiquement sa sélection à partir de l'en-tête HTTP Host fourni par le client, lorsque la correspondance la plus exacte du point de vue adresse IP/port a lieu pour plusieurs serveurs virtuels.

La directive ServerName peut apparaître en quelque endroit de la définition d'un serveur. Cependant, chaque occurrence écrase la précédente (pour ce serveur). Si aucune directive ServerName n'est spécifiée, le serveur tente de déterminer le nom du serveur à partir de l'adresse IP.

Le premier serveur virtuel à base de nom apparaissant dans le fichier de configuration pour une paire IP:port donnée est significatif car c'est lui qui sera utilisé pour toutes les requêtes reçues sur cette adresse IP/port et pour laquelle aucun autre serveur virtuel ne possède un ServerName ou un ServerAlias correspondant. Il sera aussi utilisé pour toutes les connexions SSL si le serveur ne supporte pas l'Indication du nom du serveur.

Tous les noms spécifiés au sein d'une section VirtualHost sont traités comme un ServerAlias (sans caractères génériques), mais ne sont écrasés par aucune directive ServerAlias.

Pour chaque serveur virtuel, diverses valeurs sont initialisées par défaut. En particulier :

  1. Dans le cas où un serveur virtuel ne contient pas de directives ServerAdmin, Timeout, KeepAliveTimeout, KeepAlive, MaxKeepAliveRequests, ReceiveBufferSize, ou SendBufferSize, alors la valeur de chacun de ces paramètres est héritée de celle du serveur principal. (C'est à dire, héritée de la valeur finale après lecture de la configuration du serveur principal.)
  2. Les permissions par défaut sur les répertoires de chaque serveur virtuel sont assemblées avec celles du serveur principal. Elles concernent également toutes les informations de configuration par répertoire pour tous les modules.
  3. Les configurations par serveur pour chaque module sont assemblées à partir de celles du serveur principal.

L'essentiel des valeurs de configuration des serveurs virtuels provient de valeurs par défaut issues du serveur principal. Mais la position dans le fichier de configuration des directives du serveur principal n'a pas d'importance -- l'ensemble de la configuration du serveur principal est lu avant que ces valeurs par défaut soient appliquées aux serveur virtuels. Ainsi, même si la définition d'une valeur apparaît après celle d'un serveur virtuel, cette valeur peut affecter la definition du serveur virtuel.

Dans le cas où le serveur principal n'a pas de ServerName à ce stade, le nom de la machine sur laquelle tourne le programme httpd est utilisé à sa place. Nous appellerons jeu d'adresses du serveur principal les adresses IP renvoyées par une résolution DNS sur le ServerName du serveur principal.

Pour tous les champs ServerName non définis, dans le cas d'une configuration en serveur virtuel par nom, la valeur adoptée par défaut est la première adresse donnée dans la section VirtualHost qui définit le serveur virtuel.

Si un serveur virtuel contient la valeur magique _default_, il fonctionne sur le même ServerName que le serveur principal.

Choix du serveur virtuel

À la réception d'une requête, le serveur procède comme suit pour déterminer quel serveur virtuel utiliser :

Recherche de l'adresse IP

Lors d'une première connexion sur une adresse/port, le serveur recherche toutes les directives VirtualHost qui possèdent la même adresse IP/port.

S'il n'y a aucune correspondance exacte pour cette adresse/port, la recherche s'effectue sur la valeur générique (*).

Si aucune correspondance n'est enfin trouvée, la requête sera servie par le serveur principal.

S'il existe des définitions VirtualHost pour l'adresse IP, l'étape suivante consiste à déterminer si nous avons à faire à un serveur virtuel à base de nom ou d'adresse IP.

Serveur virtuel par IP

Si une seule section VirtualHost présente la meilleure correspondance avec la paire adresse IP/port, aucune action n'est entreprise et la requête est traitée par le serveur virtuel qui correspond.

Serveur virtuel par nom

Si plusieurs sections VirtualHost présentent la meilleure correspondance avec la paire adresse IP/port, le terme "liste" dans les étapes suivantes fait référence à la liste des serveurs virtuels qui correspondent, selon l'ordre dans lequel ils apparaissent dans le fichier de configuration.

Si la connexion utilise SSL, si le serveur supporte l'Indication de nom de serveur, et si la négociation du client SSL inclut l'extension TLS dans le nom d'hôte requis, alors ce nom d'hôte sera utilisé par la suite, tout comme un en-tête Host: aurait été utilisé dans le cas d'une connexion non-SSL. Si ces conditions ne sont pas réunies, le premier serveur virtuel à base de nom dont l'adresse correspond sera utilisé pour les connexions SSL. Ceci est important car c'est le serveur virtuel qui détermine quel certificat le serveur va utiliser pour la connexion.

Si la requête contient un en-tête Host:, on recherche dans la liste le premier serveur virtuel dont le ServerName ou le ServerAlias correspond, et c'est celui-ci qui va traiter la requête. Un en-tête Host: peut comporter un numéro de port mais Apache l'ignore systématiquement et utilise toujours le port sur lequel il a effectivement reçu la requête.

Le premier serveur virtuel du fichier de configuration qui possède l'adresse spécifiée est prioritaire et intercepte toutes les requêtes à destination d'un nom de serveur inconnu, ou toute requête sans en-tête Host: (comme les requêtes HTTP/1.0).

Connexions persistantes

La recherche par adresse IP décrite ci-avant n'est faite qu'une fois pour chaque session TCP/IP, alors que la recherche par nom est réalisée pour chaque requête au cours d'une connexion persistante (KeepAlive). En d'autres termes, il est possible pour un client de faire des requêtes sur différents serveurs virtuels par nom, au cours d'une unique connexion persistante.

URI absolu

Au cas où l'URI de la requête est absolu, et que son nom de serveur et son port correspondent au serveur principal (ou l'un des serveurs virtuels configurés), et qu'ils correspondent à l'adresse et au port de la requête, alors l'URI est amputé de son préfixe protocole/nom de serveur/port et traité par le serveur correspondant (principal ou virtuel). Si cette correspondance n'existe pas, l'URI reste inchangé et la requête est considérée comme une requête d'un serveur mandataire (proxy).

Observations

  • La sélection d'un serveur virtuel en fonction de son nom est un processus qui intervient après la sélection par le serveur du serveur virtuel qui correspond le mieux du point de vue adresse IP/port.
  • Si vous ne tenez pas compte de l'adresse IP à laquelle le client s'est connecté, indiquez un caractère "*" comme adresse pour tous les serveurs virtuels, et la sélection du serveur virtuel en fonction du nom s'appliquera alors à tous les serveurs virtuels définis.
  • Les vérifications sur ServerName et ServerAlias ne sont jamais réalisées pour les serveurs virtuels par IP.
  • Seul l'ordre des serveurs virtuels par nom pour une adresse donnée a une importance. Le serveur virtuel par nom qui est présent en premier dans la configuration se voit attribué la priorité la plus haute pour les requêtes arrivant sur son jeu d'adresses IP.
  • Le numéro de port contenu dans l'en-tête Host: n'est jamais utilisé pour les tests de correspondances. Apache ne prend en compte que le numéro de port sur lequel le client a envoyé la requête.
  • Si deux serveurs virtuels partagent la même adresse, la sélection se fera implicitement sur le nom. Il s'agit d'une nouvelle fonctionnalité de la version 2.3.11.
  • Le serveur principal ne sert les requêtes que lorsque l'adresse IP et le port demandés par le client ne correspondent à aucun serveur virtuel (y compris un serveur virtuel *). En d'autres termes, le serveur principal n'est utile que pour les combinaisons adresse/port non spécifiées (sauf quand un serveur virtuel _default_ correspond au port).
  • Il ne faut jamais employer de noms DNS dans des directives VirtualHost, car cela oblige le serveur a s'appuyer sur le DNS au moment du démarrage. De plus, vous vous exposez à des problèmes de sécurité si vous n'avez pas la maîtrise du DNS pour la totalité de vos domaines. Voir la documentation disponible ici, ainsi que les deux points précisés ci-après.
  • Un nom de serveur ServerName devrait toujours être indiqué pour chaque serveur virtuel. Sans cela, une résolution DNS est nécessaire pour chaque serveur virtuel.

Trucs et astuces

En plus des points évoqués sur la page des problèmes liés au DNS, voici quelques points intéressants :

  • Toujours positionner les définitions relatives au serveur principal avant toute définition VirtualHost. (Ceci améliore grandement la lisibilité de la configuration -- la manière dont la configuration est interprétée après la lecture des fichiers ne met pas en évidence le fait que les définitions positionnées avant et surtout après les serveurs virtuels peuvent impacter le fonctionnement de tous les serveurs virtuels.)


Limites des descripteurs de fichiers - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Serveurs Virtuels

Limites des descripteurs de fichiers

Quand de nombreux serveurs virtuels sont créés, Apache peut dépasser les limites en descripteurs de fichiers ('file descriptors', également appelés gestionnaires de fichiers) si chacun des serveurs virtuels utilise ses propres fichiers journaux. Le nombre total de descripteurs de fichiers utilisés par Apache est d'un par fichier journal, un pour chacune des autres directives de fichiers journaux, plus un nombre constant compris entre 10 et 20 pour son fonctionnement interne. Les systèmes d'exploitation Unix limitent le nombre de descripteurs de fichiers utilisables par processus ; une valeur courante pour cette limite est de 64, et cette valeur peut le plus souvent être augmentée.

Apache tente d'accroître cette valeur limite si nécessaire, mais sans y parvenir dans les cas suivants :

  1. Le système d'exploitation ne permet pas l'utilisation d'appels systèmes setrlimit().
  2. L'appel setrlimit(RLIMIT_NOFILE) ne fonctionne pas sur votre système d'exploitation (c'est le cas sous Solaris 2.3).
  3. Le nombre de descripteurs de fichiers nécessaires à Apache dépasse la limite physique du matériel.
  4. Le système impose d'autres limites sur l'utilisation des descripteurs de fichiers, comme par exemple une limite sur les flux stdio, utilisables uniquement sur les descripteurs de fichiers inférieurs à 256. (sous Solaris 2).

En cas de problème, Vous pouvez :

  • Réduire le nombre de fichiers journaux, en ne spécifiant aucun fichier journal dans les sections <VirtualHost>, en donc en envoyant les informations aux fichiers journaux du serveur principal (Voir Éclatement des fichiers journaux ci-dessous pour plus d'informations sur cette possibilité).
  • Dans les cas 1 ou 2 (évoqués ci-dessus), augmentez la limite sur les descripteurs de fichiers avant le démarrage d'Apache, au moyen d'un script comme

    #!/bin/sh
    ulimit -S -n 100
    exec httpd

Éclatement des fichiers journaux

Lorsque vous choisissez d'enregistrer les informations émanant de plusieurs serveurs virtuels dans un même fichier journal, vous voudrez ensuite pouvoir scinder ces informations à des fins de statistiques, par exemple, sur les différents serveurs virtuels. Il est possible de procéder de la manière suivante :

Tout d'abord, vous devez ajouter le nom du serveur virtuel à chaque entrée du journal. Ceci se paramètre au moyen de la directive LogFormat et de la variable %v. Ajoutez cette variable au début de la chaîne de définition du format de journalisations :

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost
CustomLog logs/multiple_vhost_log vhost

Cette configuration va provoquer la création d'un fichier de journalisation au format standard (CLF : 'Common Log Format'), mais dont chaque ligne débutera par le nom canonique du serveur virtuel (spécifié par la directive ServerName). (Voir mod_log_config pour d'autres informations sur la personnalisation des fichiers journaux.)

Au moment de séparer les informations du fichier journal en un fichier par serveur virtuel, le programme split-logfile peut être utilisé. Ce programme peut être trouvé dans le répertoire support de la distribution d'Apache.

Exécutez ce programme au moyen de la commande :

split-logfile < /logs/multiple_vhost_log

Une fois exécuté avec le nom du fichier contenant tous les journaux, ce programme va générer un fichier pour chacun des serveurs virtuels qui apparaît dans le fichier d'entrée. Chaque fichier en sortie est nommé nomduserveur.log.


Le module Apache mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Le module Apache mod_rewrite

mod_rewrite permet de modifier les requêtes entrantes dynamiquement, en fonction de règles manipulant des expressions rationnelles. Vous pouvez ainsi relier des URLs arbitraires à votre propre structure d'URLs interne comme vous le souhaitez.

Il fournit un mécanisme de manipulation d'URL particulièrement souple et puissant en supportant un nombre illimité de règles et de conditions attachées à chaque règle. Les manipulations d'URLs peuvent dépendre de tests variés : les URLs peuvent être finement caractérisées en fonction de variables du serveur, de variables d'environnement, d'en-têtes HTTP, de repères temporels, de recherches dans des bases de données externes, ou même de requêtes vers des bases de données externes et de différents gestionnaires ou programmes externes.

Les règles de réécriture peuvent agir sur l'ensemble des URLs (la partie chemin et la chaîne de paramètres) et peuvent être utilisées dans le contexte du serveur principal (httpd.conf), mais aussi dans le contexte des serveurs virtuels (sections <VirtualHost>), ou dans le contexte des répertoires (fichiers .htaccess et blocs <Directory>. Le résultat réécrit peut conduire vers d'autres règles à un traitement secondaire interne, une redirection vers une requête externe ou même l'envoi vers un serveur mandataire, en fonction des drapeaux que vous attachez aux règles

mod_rewrite étant très puissant, il peut par conséquent être très complexe. Ce document complète la documentation de référence du module mod_rewrite, et est sensé alléger un peu cette complexité, et présenter des exemples largement commentés, ainsi que des situations courantes que vous pourrez traiter avec mod_rewrite. Mais nous voulons aussi vous montrer des situations où vous ne devrez pas utiliser mod_rewrite, et lui préférer d'autres fonctionnalités standard d'Apache, évitant ainsi d'entrer dans une complexité inutile.

  • documentation de référence de mod_rewrite
  • Introduction aux expressions rationnelles et à mod_rewrite
  • Utilisation de mod_rewrite pour la redirection et la remise en correspondance avec le système de fichiers des URLs
  • Utilisation de mod_rewrite pour le contrôle d'accès
  • Les serveurs virtuels dynamiques avec mod_rewrite
  • Les serveurs mandataires dynamiques avec mod_rewrite
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand NE PAS utiliser mod_rewrite
  • Drapeaux de réécriture
  • Détails techniques

Voir aussi

  • Documentation de référence de mod_rewrite
  • Mise en correspondance des URLs avec le système de fichiers
  • wiki mod_rewrite
  • Glossaire


mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

Module Apache mod_rewrite

Description: | Ce module fournit un moteur de réécriture à base de règles permettant de réécrire les URLs des requêtes à la volée
Statut: | Extension
Identificateur de Module: | rewrite_module
Fichier Source: | mod_rewrite.c

Sommaire

Le module mod_rewrite utilise un moteur de réécriture à base de règles, basé sur un interpréteur d'expressions rationnelles PCRE, pour réécrire les URLs à la volée. Par défaut, mod_rewrite met en correspondance une URL avec le système de fichiers. Cependant, on peut aussi l'utiliser pour rediriger une URL vers une autre URL, ou pour invoquer une requête interne à destination du mandataire.

mod_rewrite fournit une méthode souple et puissante pour manipuler les URLs en utilisant un nombre illimité de règles. Chaque règle peut être associée à un nombre illimité de conditions, afin de vous permettre de réécrire les URLs en fonction de variables du serveur, de variables d'environnement, d'en-têtes HTTP, ou de repères temporels.

mod_rewrite agit sur la totalité de l'URL, y compris la partie chemin. Une règle de réécriture peut être invoquée dans httpd.conf ou dans un fichier .htaccess. Le chemin généré par une règle de réécriture peut inclure une chaîne de paramètres, ou peut renvoyer vers un traitement secondaire interne, une redirection vers une requête externe ou vers le mandataire interne.

Vous trouverez d'avantage de détails, discussions et exemples dans la documentation détaillée sur mod_rewrite.

Journalisation

mod_rewrite offre une journalisation détaillée de ses actions aux niveaux de journalisation trace1 à trace8. Le niveau de journalisation peut être défini de manière spécifique à mod_rewrite via la directive LogLevel : jusqu'au niveau debug aucune action n'est journalisée, alors qu'elles le sont pratiquement toutes au niveau trace8.

L'utilisation d'un niveau de journalisation élevé pour mod_rewrite va ralentir votre serveur HTTP Apache de manière dramatique ! N'utilisez un niveau de journalisation supérieur à trace2 qu'à des fins de débogage !

Exemple

LogLevel alert rewrite:trace3

RewriteLog

Ceux qui sont familiers avec les versions précédentes de mod_rewrite vont probablement rechercher en vain les directives RewriteLog et RewriteLogLevel. Elles ont été en effet remplacées par une configuration de la journalisation par module, comme mentionné plus haut.

Pour extraire les traces spécifiques à mod_rewrite, affichez le fichier journal en redirigeant la sortie vers grep :

tail -f error_log|fgrep '[rewrite:'

Directive RewriteBase

Description: | Définit l'URL de base pour les réécritures au niveau répertoire
Syntaxe: | RewriteBase chemin_URL
Défaut: | Pas de valeur par défaut
Contexte: | répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_rewrite

La directive RewriteBase permet de spécifier le préfixe d'URL à utiliser dans un contexte de répertoire (htaccess) pour les directives RewriteRule qui réécrivent vers un chemin relatif.

Cette directive est obligatoire si vous utilisez un chemin relatif dans une substitution, et dans un contexte de répertoire (htaccess), sauf si au moins une de ces conditions est vérifiée :

  • La requête initiale, ainsi que la substitution, se situent par raport à la valeur de la directive DocumentRoot (c'est à dire que pour y accéder, il n'est pas nécessaire d'utiliser une directive telle qu'Alias).
  • Le chemin du système de fichiers vers le répertoire contenant la RewriteRule, suffixé par la substitution relative est aussi valide en tant qu'URL sur le serveur (ce qui est rare).
  • A partir de la version 2.4.16 du serveur HTTP Apache, cette directive peut être omise lorsque la requête est mise en correspondance avec le système de fichiers via la directive Alias ou le module mod_userdir.

Dans l'exemple ci-dessous, la directive RewriteBase est nécessaire afin d'éviter une réécriture en http://example.com/opt/myapp-1.2.3/welcome.html car la ressource n'était pas relative à la racine des documents. Cette erreur de configuration aurait conduit le serveur à rechercher un répertoire "opt" à la racine des documents.

DocumentRoot "/var/www/example.com"
AliasMatch "^/myapp" "/opt/myapp-1.2.3"
<Directory "/opt/myapp-1.2.3">
 RewriteEngine On
    RewriteBase "/myapp/"
    RewriteRule "^index\.html$"  "welcome.html"
</Directory>

Directive RewriteCond

Description: | Définit une condition qui devra être satisfaite pour que la réécriture soit effectuée
Syntaxe: | RewriteCond chaîne_de_test expression_de_comparaison [drapeaux]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_rewrite

La directive RewriteCond permet de définir une condition d'exécution d'une règle. Une ou plusieurs conditions RewriteCond peuvent précéder une directive RewriteRule. La règle de réécriture correspondante n'est ainsi exécutée que si ces conditions sont satisfaites, et si l'URI correspond au modèle spécifié dans la règle.

TestString est une chaîne qui peut contenir les extensions suivantes en plus du texte simple :

  • références arrières de règle de réécriture : ce sont des références arrières de la forme $N (0 <= N <= 9). $1 à $9 permettent d'accéder aux parties regroupées (entre parenthèses) du modèle, issues de la RewriteRule concernée par le jeu de conditions RewriteCond courant. $0 donne accès à l'ensemble de la chaîne correspondant au modèle.
  • Références arrières de condition de réécriture : ce sont des références arrières de la forme %N (0 <= N <= 9). %1 à %9 permettent d'accéder aux parties regroupées (entre parenthèses) du modèle, issues de la dernière condition RewriteCond satisfaite du jeu de conditions RewriteCond courant. %0 donne accès à l'ensemble de la chaîne correspondant au modèle.
  • extensions de table de réécriture : ce sont des extensions de la forme ${nomTable:clé|défaut}. Voir la href="#mapfunc">documentation sur RewriteMap pour plus de détails.
  • Variables du serveur : ce sont des variables de la forme %{ NAME_OF_VARIABLE }, où NOM_DE_VARIABLE peut contenir une chaîne issue de la liste suivante :
    En-têtes HTTP : connexion & requête:
    HTTP_ACCEPT
    HTTP_COOKIE
    HTTP_FORWARDED
    HTTP_HOST
    HTTP_PROXY_CONNECTION
    HTTP_REFERER
    HTTP_USER_AGENT
             AUTH_TYPE
    CONN_REMOTE_ADDR
    CONTEXT_PREFIX
    CONTEXT_DOCUMENT_ROOT
    IPV6
    PATH_INFO
    QUERY_STRING
    REMOTE_ADDR
    REMOTE_HOST
    REMOTE_IDENT
    REMOTE_PORT
    REMOTE_USER
    REQUEST_METHOD
    SCRIPT_FILENAME
    variables internes au serveur : date et heure : spéciaux :
    DOCUMENT_ROOT
    SCRIPT_GROUP
    SCRIPT_USER
    SERVER_ADDR
    SERVER_ADMIN
    SERVER_NAME
    SERVER_PORT
    SERVER_PROTOCOL
    SERVER_SOFTWARE
             TIME_YEAR
    TIME_MON
    TIME_DAY
    TIME_HOUR
    TIME_MIN
    TIME_SEC
    TIME_WDAY
    TIME
             API_VERSION
    CONN_REMOTE_ADDR
    HTTPS
    IS_SUBREQ
    REMOTE_ADDR
    REQUEST_FILENAME
    REQUEST_SCHEME
    REQUEST_URI
    THE_REQUEST

    Ces variables correspondent toutes aux en-têtes MIME HTTP de mêmes noms, au variables C du serveur HTTP Apache, ou aux champs struct tm du système Unix. La plupart d'entre elles sont documentées ici, dans la spécification CGI ou ailleurs dans le manuel.

    SERVER_NAME et SERVER_PORT dépendent respectivement des valeurs des directives UseCanonicalName et UseCanonicalPhysicalPort.

    Parmi les variables spécifiques à mod_rewrite, ou trouve les suivantes :

    API_VERSION
    C'est la version de l'API des modules Apache httpd (l'interface interne entre le serveur et les modules) pour la construction courante de httpd, telle qu'elle est définie dans include/ap_mmn.h. La version de l'API des modules correspond à la version du serveur Apache httpd utilisé (par exemple, pour la version 1.3.14 d'Apache httpd, il s'agit de la version 19990320:10), mais intéresse principalement les auteurs de modules.
    CONN_REMOTE_ADDR
    A partir de la version 2.4.8 : l'adresse IP distante de la connexion (voir le module mod_remoteip).
    HTTPS
    Contient le texte "on" si la connexion utilise SSL/TLS, "off" dans le cas contraire (Cette variable peut être utilisée sans problème, que mod_ssl soit chargé ou non).
    IS_SUBREQ
    Contient le texte "true" si la requête en cours de traitement est une sous-requête, "false" dans le cas contraire. Une sous-requête est générée quand un module a besoin de se référer à des fichiers ou URIs addidionnels pour pouvoir mener à bien sa tâche.
    REMOTE_ADDR
    L'adresse IP de l'hôte distant (se référer au module mod_remoteip).
    REQUEST_FILENAME
    Le chemin complet local au système de fichiers du fichier ou du script correspondant à la requête, s'il a déjà été déterminé par le serveur au moment où on y fait référence. Dans le cas contraire, et en particulier dans le cas d'un serveur virtuel, REQUEST_FILENAME contient la valeur de REQUEST_URI. En fonction de la valeur de la directive AcceptPathInfo, le serveur peut n'utiliser que certains éléments de tête du REQUEST_URI pour déterminer à quel fichier correspond la requête.
    REQUEST_SCHEME
    Contient le protocole de la requête (en général "http" ou "https"). La valeur peut être modifiée par la directive ServerName.
    REQUEST_URI
    La partie chemin de l'URI de la requête, comme "/index.html". Ceci exclut en particulier la chaîne de paramètres de la requête qui est contenue dans la variable QUERY_STRING.
    THE_REQUEST
    La ligne de requête HTTP complète envoyée par le navigateur au serveur (par exemple, "GET /index.html HTTP/1.1"), à l'exclusion de tout en-tête ajouté par le navigateur. Cette valeur n'a pas été déséchappée (décodée), à la différence de la plupart des variables suivantes.

Si la chaîne_de_test contient la valeur spéciale expr, expression_de_comparaison sera traité en tant qu'expression rationnelle de type ap_expr. Si des en-têtes HTTP sont référencés dans l'expression rationnelle, et si le drapeau novary n'est pas activé, ils seront ajoutés à l'en-tête Vary.

Autres points à connaître ::

  1. Les variables SCRIPT_FILENAME et REQUEST_FILENAME contiennent toutes deux la valeur du champ filename de la structure interne request_recdu serveur HTTP Apache. Le premier nom correspond au nom de variable bien connu CGI, alors que le second est l'équivalent de REQUEST_URI (qui contient la valeur du champ uri de request_rec).

    Si une substitution intervient et si la réécriture se poursuit, la valeur des deux variables sera mise à jour en conséquence.

    Dans le contexte du serveur principal (c'est à dire avant que la requête ne soit mise en correspondance avec le système de fichiers), SCRIPT_FILENAME et REQUEST_FILENAME ne peuvent pas contenir le chemin entier dans le système de fichiers local car ce chemin b'est pas connu à ce stade du traitement. Dans ce cas, les deux variables contiendront la valeur de REQUEST_URI. Pour obtenir le chemin complet de la requête dans le système de fichiers local dans le contexte du serveur principal, utilisez une référence avant à base d'URL %{LA-U:REQUEST_FILENAME} pour déterminer la valeur finale de REQUEST_FILENAME.

  2. %{ENV:variable}, où variable peut correspondre à une variable d'environnement quelconque.
  3. %{ENV:variable} est aussi disponible, où variable peut correspondre à toute variable d'environnement. Peut être consulté via des structures internes d'Apache httpd et (si on ne les trouve pas ici) via la fonction getenv() à partir du processus du serveur Apache httpd.
  4. Que mod_ssl soit chargé ou non, on peut utiliser %{SSL:variable}, où variable peut être remplacé par le nom d'une variable d'environnement SSL . Si mod_ssl n'est pas chargé, cette variable contiendra toujours une chaîne vide. Exemple : %{SSL:SSL_CIPHER_USEKEYSIZE} pourra contenir la valeur 128. Ces variables sont disponibles même si l'option StdEnvVars de la directive SSLOptions n'a pas été définie.
  5. On peut utiliser %{HTTP:en-tête}, où en-tête peut correspondre à tout nom d'en-tête MIME HTTP, pour extraire la valeur d'un en-tête envoyé dans la requête HTTP. Par exemple, %{HTTP:Proxy-Connection} contiendra la valeur de l'en-tête HTTP "Proxy-Connection:". Si on utilise un en-tête HTTP dans une condition, et si cette condition est évaluée à vrai pour la requête, cet en-tête sera ajouté à l'en-tête Vary de la réponse. Il ne le sera pas si la condition est évaluée à faux. L'ajout de l'en-tête HTTP à l'en-tête Vary est nécessaire à une mise en cache appropriée.

    Il faut garder à l'esprit que les conditions suivent une logique de cout-circuit si le drapeau 'ornext|OR' est utilisé, et que de ce fait, certaines d'entre elles ne seront pas évaluées.

  6. A des fins de référence avant, on peut utiliser, %{LA-U:variable}, qui permet d'effectuer une sous-requête interne à base d'URL, afin de déterminer la valeur finale de variable. Ceci permet d'accéder à la valeur d'une variable pour la réécriture inconnue à ce stade du traitement, mais qui sera définie au cours d'une phase ultérieure.

    Par exemple, pour effectuer une réécriture dépendant de la variable REMOTE_USER dans le contexte du serveur principal (fichier httpd.conf), vous devez utiliser %{LA-U:REMOTE_USER} - cette variable est définie par la phase d'autorisation qui intervient après la phase de traduction d'URL (pendant laquelle mod_rewrite opère).

    Par contre, comme mod_rewrite implémente son contexte de répertoire (fichier .htaccess) via la phase Fixup de l'API, et comme la phase d'autorisation intervient avant cette dernière, vous pouvez vous contenter d'utiliser %{REMOTE_USER} dans ce contexte.

  7. %{LA-F:variable} peut être utilisée pour effectuer une sous-requête interne (basée sur le nom de fichier), afin de déterminer la valeur finale de variable. La plupart du temps, elle est identique à LA-U (voir ci-dessus).

expression_de_comparaison est une expression rationnelle qui est appliquée à l'instance actuelle de chaîne_de_test. chaîne_de_test est d'abord évaluée, puis comparée à l'expression_de_comparaison.

expression_de_comparaison est en général une expression rationnelle compatible perl, mais vous disposez des syntaxes supplémentaires suivantes pour effectuer d'autres tests utiles sur chaîne_de_test :

  1. Vous pouvez préfixer l'expression avec un caractère '!' (point d'exclamation) pour inverser le résultat de la condition, quelle que soit l'expression de comparaison utilisée.
  2. Vous pouvez effectuer des comparaisons lexicographiques de chaînes :
    <expression
    inférieur au sens lexicographique
    Traite l'expression comme une chaîne de caractères et la compare lexicographiquement à chaîne_de_test. La condition est satisfaite si chaîne_de_test est inférieure au sens lexicographique à l'expression.
    >expression
    supérieur au sens lexicographique
    Traite l'expression comme une chaîne de caractères et la compare lexicographiquement à chaîne_de_test. La condition est satisfaite si chaîne_de_test est supérieure au sens lexicographique à l'expression.
    =expression
    égal au sens lexicographique
    Traite l'expression comme une chaîne de caractères et la compare lexicographiquement à chaîne_de_test. La condition est satisfaite si chaîne_de_test est égale au sens lexicographique à l'expression (les deux chaînes sont exactement identiques, caractère pour caractère). Si expression est "" (deux guillemets), chaîne_de_test est comparée à la chaîne vide.
    <=expression de comparaison
    inférieur ou égal à au sens lexicographique
    Considère l'expression_de_comparaison comme une chaîne de caractères et la compare au sens lexicographique à la chaîne_de_test. Vrai si chaîne_de_test précède lexicographiquement expression_de_comparaison, ou est égale à expression_de_comparaison (les deux chaînes sont identiques, caractère pour caractère).
    >=expression de comparaison
    supérieur ou égal à au sens lexicographique
    Considère l'expression_de_comparaison comme une chaîne de caractères et la compare au sens lexicographique à la chaîne_de_test. Vrai si chaîne_de_test suit lexicographiquement expression_de_comparaison, ou est égale à expression_de_comparaison (les deux chaînes sont identiques, caractère pour caractère).
  3. Vous pouvez effectuer des comparaisons d'entiers :
    -eq
    est numériquement égal à
    La chaîne_de_test est considérée comme un entier, et est comparée numériquement à l'expression de comparaison. Vrai si les deux expressions sont numériquement égales.
    -ge
    est numériquement supérieur ou égal à
    La chaîne_de_test est considérée comme un entier, et est comparée numériquement à l'expression de comparaison. Vrai si chaîne_de_test est numériquement supérieure ou égale à expression_de_comparaison.
    -gt
    est numériquement supérieur à
    La chaîne_de_test est considérée comme un entier, et est comparée numériquement à l'expression de comparaison. Vrai si chaîne_de_test est numériquement supérieure à expression_de_comparaison.
    -le
    est numériquement inférieur ou égal à
    La chaîne_de_test est considérée comme un entier, et est comparée numériquement à l'expression de comparaison. Vrai si chaîne_de_test est numériquement inférieure ou égale à expression_de_comparaison. Attention à la confusion avec le drapeau -l en utilisant la variante the -L ou -h.
    -lt
    est numériquement inférieur à
    La chaîne_de_test est considérée comme un entier, et est comparée numériquement à l'expression de comparaison. Vrai si chaîne_de_test est numériquement inférieure à expression_de_comparaison. Attention à la confusion avec le drapeau -l en utilisant la variante the -L ou -h.
    -ne
    Est numériquement non égal à
    La Chaîne de test est considérée comme un entier et est numériquement comparée à l'expression de comparaison. Vrai si les deux éléments comparés sont numériquement différents. Equivalent à !-eq.
  4. Vous pouvez effectuer différents tests sur les attributs de fichier :
    -d
    est un répertoire
    Traite chaîne_de_test comme un chemin et vérifie s'il existe ou pas, et s'il s'agit d'un répertoire.
    -f
    est un fichier régulier
    Traite chaîne_de_test comme un chemin et vérifie s'il existe ou pas, et s'il s'agit d'un fichier régulier.
    -F
    test de l'existence d'un fichier via une sous-requête
    Vérifie si chaîne_de_test est un fichier valide, accessible à travers tous les contrôles d'accès du serveur actuellement configurés pour ce chemin. C'est une sous-requête interne qui effectue cette vérification - à utiliser avec précautions car les performances du serveur peuvent s'en trouver affectées !
    -h
    est un lien symbolique, selon la convention bash
    Voir -l.
    -l
    est un lien symbolique
    Considère la chaîne_de_test comme un chemin et vérifie son existence et si elle est un lien symbolique. On peut aussi utiliser la convention bash -L ou -h lorsqu'il y a risque de confusion avec les tests -lt ou -le.
    -L
    est un lien symbolique, selon la convention bash
    Voir -l.
    -s
    est un fichier régulier d'une certaine taille
    Considère la chaîne_de_test comme un chemin et vérifie son existence et si elle est un fichier régulier d'une taille supérieure à zéro.
    -U

    test de l'existence d'une URL via une sous-requête
    Vérifie si chaîne_de_test est une URL valide, accessible à travers tous les contrôles d'accès du serveur actuellement configurés pour ce chemin. C'est une sous-requête interne qui effectue cette vérification - à utiliser avec précautions car les performances du serveur peuvent s'en trouver affectées !

    Ce drapeau ne renvoie que des informations concernant le contrôle d'accès, l'authentification et l'autorisation. Il ne renvoie pas d'informations concernant le code d'état que le gestionnaire configuré (static file, CGI, proxy, etc...) aurait, quant à lui, retourné.

    -x
    a l'attribut d'exécution positionné
    Considère la chaîne_de_test comme un chemin et vérifie son existence et si elle a son attribut d'exécution positionné. Ce positionnement est déterminé en fonction de l'OS sous-jacent.
    Par exemple:
    RewriteCond /var/www/%{REQUEST_URI} !-f
RewriteRule ^(.+) /other/archive/$1 [R]

  5. Si la chaîne_de_test contient la valeur spéciale expr, la chaîne de comparaison sera traitée en tant qu'expression rationnelle de type ap_expr.

    Dans l'exemple ci-dessous, on utilise -strmatch pour comparer le REFERER avec le nom d'hôte du site afin de bloquer le hotlinking (référencement direct) non désiré.

               RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"
           RewriteRule "^/images" "-" [F]

Vous pouvez aussi définir certains drapeaux pour l'expression_de_comparaison en ajoutant ces [drapeaux] comme troisième argument de la directive RewriteCond, où drapeaux est un sous-ensemble séparé par des virgules des drapeaux suivants :

  • 'nocase|NC' (no case)
    Rend le test insensible à la casse - il n'est pas fait de distinction entre majuscules et minuscules, à la fois dans le développement de chaîne_de_test et dans expression_de_comparaison. Ce drapeau n'est pris en compte que lors d'une comparaison entre chaîne_de_test et expression_de_comparaison. Il ne l'est pas pour les vérification par sous-requêtes ou sur le système de fichiers.
  • 'ornext|OR' (ou condition suivante)
    Permet de chaîner les conditions de règles avec un OU au lieu du AND implicite. Exemple typique :
    RewriteCond "%{REMOTE_HOST}"  "^host1"  [OR]
RewriteCond "%{REMOTE_HOST}"  "^host2"  [OR]
RewriteCond "%{REMOTE_HOST}"  "^host3"
RewriteRule ...règles concernant tous ces hôtes...
    Sans ce drapeau, les paires condition/règle devraient être écrites trois fois.
  • 'novary|NV' (no vary)
    Si la condition contient un en-tête HTTP, ce drapeau empêche ce dernier d'être ajouté à l'en-tête Vary de la réponse.
    L'utilisation de ce drapeau peut provoquer une mise en cache incorrecte de la réponse, si la représentation de cette réponse varie avec la valeur de l'en-tête considéré. Ce drapeau ne devrait donc être utilisé que si l'on maîtrise parfaitement le fonctionnement de l'en-tête Vary.

Exemple :

Pour réécrire la page d'accueil d'un site en fonction de l'en-tête ``User-Agent:'' de la requête, vous pouvez utiliser ce qui suit :

RewriteCond  "%{HTTP_USER_AGENT}"  "(iPhone|Blackberry|Android)"
RewriteRule  "^/$"               "/homepage.mobile.html"  [L]

RewriteRule  "^/$"                 "/homepage.std.html"  [L]

Explications : si vous utilisez un navigateur qui s'identifie comme un navigateur de plateforme mobile (notez que l'exemple est incomplet car il existe de nombreuses autres plateformes mobiles), c'est la version pour mobile de la page d'accueil qui sera renvoyée. Dans le cas contraire, ce sera la page d'accueil standard.

Directive RewriteEngine

Description: | Active ou désactive l'exécution du moteur de réécriture
Syntaxe: | RewriteEngine on|off
Défaut: | RewriteEngine off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_rewrite

La directive RewriteEngine active ou désactive l'exécution du moteur de réécriture. Si sa valeur est off, ce module n'exécutera aucun traitement et ne mettra pas à jour les variables d'environnement SCRIPT_URx.

Plutôt que de commenter toutes les directives RewriteRule, il est préférable d'utiliser cette directive si l'on souhaite désactiver les règles de réécriture dans un contexte particulier.

Notez que les hôtes virtuels n'héritent pas des configurations de réécriture. Ceci implique que vous devez insérer une directive RewriteEngine on dans chaque hôte virtuel pour lequel vous souhaitez utiliser des règles de réécriture.

Les directives RewriteMap du type prg ne sont pas prises en compte au cours de l'initialisation du serveur si elle ont été définies dans un contexte où la directive RewriteEngine n'a pas été définie à on.

Directive RewriteMap

Description: | Définit une fonction de mise en correspondance pour la recherche de mots-clés
Syntaxe: | RewriteMap MapName MapType:MapSource
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_rewrite

La directive RewriteMap définit une Table de correspondance pour la réécriture que les fonctions de mise en correspondance peuvent utiliser dans les chaînes de substitution des règles pour insérer/substituer des champs en recherchant des mots-clés. La source utilisée pour cette recherche peut être de plusieurs types.

MapName est le nom de la table de correspondance et servira à spécifier une fonction de mise en correspondance pour les chaînes de substitution d'une règle de réécriture selon une des constructions suivantes :

${ MapName : mot-clé }
${ MapName : mot-clé | valeur par défaut }

Lorsqu'une telle construction est rencontrée, la table de correspondance MapName est consultée et la clé mot-clé recherchée. Si la clé est trouvée, la construction est remplacée par la valeur de remplacement. Si la clé n'est pas trouvée, elle est remplacée par la valeur par défaut, ou par une chaîne vide si aucune valeur par défaut n'est spécifiée. La valeur vide se comporte comme si la clé était absente ; il est donc impossible de distinguer une valeur vide d'une absence de clé.

Par exemple, vous pouvez définir une directive RewriteMap comme suit

RewriteMap map-exemple "txt:/chemin/vers/fichier/map.txt"

Vous pourrez ensuite utiliser cette table dans une directive RewriteRule comme suit :

RewriteRule "^/ex/(.*)" "${map-exemple:$1}"

Les combinaisons suivantes pour type de correspondance et MapSource peuvent être utilisées :

txt
Un fichier texte contenant des paires clé-valeur séparées par des espaces, une paire par ligne (Détails ...).
rnd
Sélection aléatoire d'une entrée depuis un fichier texte (Détails ...).
dbm
Recherche une entrée dans un fichier dbm contenant des paires nom-valeur. Le condensé hash est élaboré à partir d'un format de fichier texte via l'utilitaire httxt2dbm (Détails ...).
int
Une des quatre fonctions internes disponibles que fournit RewriteMap: toupper, tolower, escape ou unescape (Détails ...).
prg
Appelle un programme externe ou un script pour effectuer la réécriture (Détails ...).
dbd or fastdbd
Une commande SQL SELECT à exécuter pour rechercher la cible de réécriture (Détails ...).

Vous trouverez plus de détails et de nombreux exemples dans le RewriteMap HowTo.

Directive RewriteOptions

Description: | Configure certaines options spéciales pour le moteur de réécriture
Syntaxe: | RewriteOptions Options
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_rewrite

La directive RewriteOptions définit certaines options spéciales pour la configuration au niveau du serveur ou du répertoire. La chaîne de caractères Option ne peut actuellement prendre qu'une des valeurs suivantes :

Inherit

Ceci force la configuration locale à hériter de la configuration du niveau supérieur. Dans le contexte des hôtes virtuels, cela signifie que les correspondances, conditions et règles du serveur principal sont héritées. Dans le contexte des répertoires, cela signifie que les conditions et règles de la configuration .htaccess ou les sections <Directory> du répertoire parent sont héritées. Les règles héritées sont virtuellement copiées dans la section où cette directive est utilisée. Si elles sont utilisées avec des règles locales, les règles héritées sont placées après ces dernières. La place de cette directive - avant ou après les règles locales - n'a aucune influence sur ce comportement. Si des règles locales ont forcé l'arrêt de la réécriture, les règles héritées ne seront pas traitées.

Les règles héritées du niveau parent sont appliquées after après les règles spécifiées dans le niveau enfant.
InheritBefore

Même effet que l'option Inherit ci-dessus, mais les règles spécifiées dans le niveau parent s'appliquent avant les règles spécifiées dans le niveau enfant.
Disponible depuis la version 2.3.10 du serveur HTTP Apache.

InheritDown

Si cette option est activée, toutes les configurations enfants hériteront de la configuration courante. Il en est de même si l'on spécifie RewriteOptions Inherit dans toutes les configurations enfants. Voir l'option Inherit pour plus de détails à propos de la manière dont les relations parent-enfants sont traitées.
Cette option est disponible à partir de la version 2.4.8 du serveur HTTP Apache.

InheritDownBefore

L'effet de cette option est équivalent à celui de l'option InheritDown ci-dessus, mais les règles de la configuration parente s'appliquent avant toute règle de la configuration enfant.
Cette option est disponible à partir de la version 2.4.8 du serveur HTTP Apache.

IgnoreInherit

Si cette option est activée, les configurations courante et enfants ignoreront toute règle héritée d'une configuration parente via les options InheritDown ou InheritDownBefore.
Cette option est disponible à partir de la version 2.4.8 du serveur HTTP Apache.

AllowNoSlash

Par défaut, mod_rewrite ignore les URLs qui correspondent à un répertoire sur disque, mais ne comportent pas de slash final, afin que le module mod_dir redirige le client vers l'URL canonique avec un slash final.

Lorsque la directive DirectorySlash est définie à off, il est possible de spécifier l'option AllowNoSlash pour s'assurer que les règles de réécriture ne soient plus ignorées. Si on le souhaite, cette option permet de faire s'appliquer des règles de réécriture qui correspondent à un répertoire sans slash final au sein de fichiers .htaccess.
Elle est disponible à partir de la version 2.4.0 du serveur HTTP Apache.

AllowAnyURI

A partir de la version 2.2.22 de httpd, lorsqu'une directive RewriteRule se situe dans un contexte de serveur virtuel ou de serveur principal, mod_rewrite ne traitera les règles de réécriture que si l'URI de la requête respecte la syntaxe d'un chemin URL. Ceci permet d'éviter certains problèmes de sécurité où des règles particulières pourraient permettre des développements de modèles inattendus (voir CVE-2011-3368 et CVE-2011-4317). Pour s'affranchir de la restriction relative à la syntaxe des chemins URL, on peut utiliser l'option AllowAnyURI, afin de permettre à mod_rewrite d'appliquer le jeu de règles à toute chaîne de requête URI, sans vérifier si cette dernière respecte la grammaire des chemins URL définie dans la spécification HTTP.
Disponible depuis la version 2.4.3 du serveur HTTP Apache.

Avertissement à propos de la sécurité

L'utilisation de cette option rendra le serveur vulnérable à certains problèmes de sécurité si les règles de réécritures concernées n'ont pas été rédigées avec soin. Il est par conséquent fortement recommandé de ne pas utiliser cette option. En particulier, prêtez attention aux chaînes en entrée contenant le caractère '@', qui peuvent modifier l'interprétation de l'URI réécrite, comme indiqué dans les liens ci-dessus.

MergeBase

Avec cette option, la valeur de la directive RewriteBase est recopiée depuis une valeur explicitement définie dans tout sous-répertoire qui ne définit pas sa propre directive RewriteBase. Il s'agissait du comportement par défaut avec les versions 2.4.0 à 2.4.3, et ce drapeau qui permet de retrouver ce comportement est disponible depuis la version 2.4.4 du serveur HTTP Apache.

IgnoreContextInfo

Lors d'une substitution relative dans un contexte de répertoire (htaccess), et si la directive RewriteBase n'a pas été définie, ce module utilise des informations en provenance d'une extension d'URL et du contexte du système de fichiers pour transformer la sustitution relative en URL. Par exemple, les modules mod_userdir et mod_alias utilisent ces informations de contexte étendu. Disponible à partir de la version 2.4.16 du serveur HTTP Apache.

LegacyPrefixDocRoot

Avant la version 2.4.26, si une substitution était une URL absolue qui correspondait au serveur virtuel courant, l'URL pouvait être tout d'abord réduite à sa partie chemin, puis enfin en chemin local. Comme l'URL peut être réduite en chemin local, le chemin doit être préfixé par la valeur de la directive DocumentRoot, ce qui permet d'interdire l'accès à un fichier tel que /tmp/myfile suite à une requête pour http://host/file/myfile avec la RewriteRule suivante :

RewriteRule /file/(.*) http://localhost/tmp/$1

Cette option permet de restaurer l'ancien comportement lorsqu'un chemin local obtenu à partir de la réduction d'une URL n'est pas préfixé par la valeur de la directive DocumentRoot. Disponible à partir de la version 2.4.26 du serveur HTTP Apache.

Directive RewriteRule

Description: | Définit les règles pour le moteur de réécriture
Syntaxe: | RewriteRule Modèle Substitution [drapeaux]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_rewrite

La directive RewriteRule est le véritable cheval de trait de la réécriture. La directive peut apparaître plusieurs fois, chaque instance définissant une règle de réécriture particulière. L'ordre dans lequel ces règles sont définies est important - il s'agit de l'ordre dans lequel les règles seront appliquées au cours du processus de réécriture.

Modèle est une expression rationnelle compatible perl. Ce avec quoi ce modèle est comparé dépend de l'endroit où la directive RewriteRule est définie.

Qu'est-ce qui est comparé ?

  • Dans un contexte de serveur virtuel VirtualHost, le modèle est tout d'abord comparé à la portion de l'URL située entre le nom d'hôte éventuellement accompagné du port, et la chaîne de paramètres (par exemple "/app1/index.html"). Il s'agit du URL-path décodé de sa valeur "%xx".

  • Dans un contexte de répertoire (sections Directory et fichiers .htaccess), le Modèle est comparé avec une partie de chemin ; par exemple une requête pour "/app1/index.html" entraînera une comparaison avec "app1/index.html" ou "index.html" selon l'endroit où la directive RewriteRule est définie.

    Le chemin où la règle est défini est supprimé du chemin correspondant du système de fichiers avant comparaison (jusqu'au slash final compris). En conséquence de cette suppression, les règles définies dans ce contexte n'effectuent des comparaisons qu'avec la portion du chemin du système de fichiers "en dessous" de l'endroit où la règle est définie.

    Le chemin correspondant actuel du système de fichiers est déterminé par des directives telles que DocumentRoot et Alias, ou même le résultat de substitutions dans des règles RewriteRule précédentes.

  • Si vous souhaitez faire une comparaison sur le nom d'hôte, le port, ou la chaîne de requête, utilisez une directive RewriteCond comportant respectivement les variables %{HTTP_HOST}, %{SERVER_PORT}, ou %{QUERY_STRING}.

Réécritures dans un contexte de répertoire

  • L'utilisation du moteur de réécriture dans les fichiers .htaccess et les sections <Directory> est un peu plus complexe.
  • Pour activer le moteur de réécriture dans ces contextes, vous devez définir "RewriteEngine On" et "Options FollowSymLinks". Si l'administrateur a désactivé la possibilité de modifier l'option FollowSymLinks au niveau du répertoire d'un utilisateur, vous ne pouvez pas utiliser le moteur de réécriture. Cette restriction a été instaurée à des fins de sécurité.
  • Voir la directive RewriteBase pour plus de détails à propos de l'ajout du préfixe après les substitutions relatives.
  • Si vous souhaitez effectuer une comparaison en prenant en compte l'intégralité du chemin de l'URL dans un contexte de répertoire (htaccess), vous devez utiliser la variable %{REQUEST_URI} dans la directive RewriteCond.
  • Le prefixe supprimé se termine toujours par un slash, ce qui signifie que la comparaison s'effectue avec une chaîne qui ne comporte jamais de slash de début. Ainsi, un modèle contenant ^/ ne correspondra jamais dans un contexte de répertoire.
  • Bien que les règles de réécriture soient permises du point de vue de la syntaxe dans les sections <Location> et <Files> (y compris leurs versions sous forme d'expression rationnelle), elles n'y sont pas prises en compte, et n'y sont à priori d'aucune utilité. Les substitutions relatives sont une fonctionnalité qui n'est, elle non-plus pas supportée dans ce genre de contexte.

Pour quelques conseils à propos des expressions rationnelles, voir le document Introduction à mod_rewrite.

Dans mod_rewrite, on peut aussi utiliser le caractère NON ('!') comme préfixe de modèle. Ceci vous permet d'inverser la signification d'un modèle, soit pour dire ``si l'URL considérée ne correspond PAS à ce modèle''. Le caractère NON peut donc être utilisé à titre exceptionnel, lorsqu'il est plus simple d'effectuer une comparaison avec le modèle inversé, ou dans la dernière règle par défaut.

Note

Si vous utilisez le caractère NON pour inverser la signification d'un modèle, vous ne pouvez pas inclure de parties génériques groupées dans le modèle. Ceci est dû au fait que, lorsque le modèle ne correspond pas (autrement dit, sa négation correspond), les groupes sont vides. Ainsi, si vous utilisez des modèles inversés, vous ne pouvez pas vous référer aux groupes par $N dans la chaîne de substitution !

Dans une règle de réécriture, Substitution est la chaîne de caractères qui remplace le chemin de l'URL original qui correspondait au Modèle. Substitution peut être :

un chemin du système de fichiers
Il indique alors la localisation dans le système de fichiers de la ressource qui doit être envoyée au client. Les substitutions ne sont traitées en tant que chemins du système de fichiers que si la règle est configurée dans un contexte de serveur (serveur virtuel), et si le premier composant du chemin dans la substitution existe dans le système de fichiers.
chemin d'URL
Un chemin relatif à la valeur de DocumentRoot vers la ressource qui doit être servie. Notez que mod_rewrite essaie de deviner si vous avez spécifié un chemin du système de fichiers ou un chemin d'URL en vérifiant si la première partie du chemin existe à la racine du système de fichiers. Par exemple, si vous avez spécifié comme chaîne de Substitution /www/file.html, cette dernière sera traitée comme un chemin d'URL à moins qu'un répertoire nommé www n'existe à la racine de votre système de fichiers (ou dans le cas d'une réécriture au sein d'un fichier .htaccess, relativement à la racine des documents), auquel cas la chaîne de substitution sera traitée comme un chemin du système de fichiers. Si vous désirez que d'autres directives de correspondance d'URL (comme la directive Alias) soient appliquées au chemin d'URL résultant, utilisez le drapeau [PT] comme décrit ci-dessous.
URL absolue
Si une URL absolue est spécifiée, mod_rewrite vérifie si le nom d'hôte correspond à celui de l'hôte local. Si c'est le cas, le protocole et le nom d'hôte sont supprimés, et ce qui reste est traité comme un chemin d'URL. Dans le cas contraire, une redirection externe vers l'URL indiquée est effectuée. Pour forcer une redirection externe vers l'hôte local, voir le drapeau [R] ci-dessous.
- (tiret)
Un tiret indique qu'aucune substitution ne doit être effectuée (le chemin considéré est transmis sans changement). Ceci est utile quand un drapeau doit être appliqué sans modifier le chemin (voir ci-dessous).

En plus du texte, la chaîne Substitution peut comporter :

  1. des références arrières ($N) vers le modèle d'une directive RewriteRule
  2. des références arrières (%N) vers le dernier modèle d'une directive RewriteCond qui correspondait
  3. des variables du serveur comme dans les chaînes de test de condition d'une règle (%{VARNAME})
  4. des appels de fonctions de comparaison (${nom correspondance:clé|défaut})

Les références arrières sont des identificateurs de la forme $N (N=0..9), qui seront remplacés par le contenu du Nème groupe du Modèle qui correspondait. Les variables du serveur sont les mêmes que dans la Chaîne_de_test d'une directive RewriteCond. Les fonctions de comparaison sont issues de la directive RewriteMap dans la section de laquelle elles sont décrites. Ces trois types de variables sont évaluées dans l'ordre ci-dessus.

Chaque règle de réécriture s'applique au résultat de la règle précédente, selon l'ordre dans lequel elles ont été définies dans le fichier de configuration. Le chemin de l'URL ou du système de fichier (voir ci-dessus Qu'est-ce qui est comparé ?) est intégralement remplacée par la chaîne de Substitution et le processus de réécriture se poursuit jusqu'à ce que toutes les règles aient été appliquées, ou qu'il soit explicitement stoppé par un drapeau L, ou par un autre drapeau qui implique un arrêt immédiat, comme END ou F.

Modifier la chaîne de requête

Par défaut, la chaîne de requête est transmise sans modification. Vous pouvez cependant créer dans la chaîne de substitution des URLs dont une partie constitue une chaîne de requête. Pour cela, ajoutez simplement un point d'interrogation dans la chaîne de substitution pour indiquer que le texte qui suit doit être réinjecté dans la chaîne de requête. Pour supprimer une chaîne de requête, terminez simplement la chaîne de substitution par un point d'interrogation. Pour combiner les nouvelles chaînes de requête avec les anciennes, utilisez le drapeau [QSA].

En outre, vous pouvez spécifier des actions spéciales à effectuer en ajoutant des [drapeaux] comme troisième argument de la directive RewriteRule. Séparés par des virgules au sein d'une liste encadrée par des crochets, les drapeaux peuvent être choisis dans la table suivante. Vous trouverez plus de détails, et des exemples pour chaque drapeau dans le document à propos des drapeaux de réécriture.

Drapeaux et syntaxe | Fonction
B | Echappe les caractères non-alphanumériques dans les références arrières avant d'appliquer la transformation. détails ...
backrefnoplus|BNP | Avec ce drapeau, si les références arrières sont échappées, les espaces seront échappés en %20 au lieu de +. Ceci s'avère utile lorsqu'une référence arrière est utilisée dans la partie chemin, et non dans la chaîne de paramètres de la requête ; pour plus de détails, voir ici.
chain|C | La règle est chaînée avec la règle suivante. Si la règle échoue, la ou les règles avec lesquelles elle est est chaînée seront sautées. détails ...
cookie|CO=NAME:VAL | Définit un cookie au niveau du navigateur client. La syntaxe complète est : CO=NAME:VAL:domain[:lifetime[:path[:secure[:httponly]]]] details ... détails ...
discardpath|DPI | Supprime la partie PATH_INFO de l'URI réécrit. détails ...
END | Stoppe le processus de réécriture immédiatement et n'applique plus aucune règle. Empêche aussi l'application ultérieure de règles de réécriture dans les contextes de répertoire et de fichier .htaccess (disponible à partir de la version 2.3.9 du serveur HTTP Apache). détails ...
env|E=[!]VAR[:VAL] | Définit la variable d'environnement VAR (à la valeur VAL si elle est fournie). La variante !VAR annule la définition de la variable VAR.détails ...
forbidden|F | Renvoie une réponse 403 FORBIDDEN au navigateur client. détails ...
gone|G | Renvoie un message d'erreur 410 GONE au navigateur client. détails ...
Handler|H=Gestionnaire de contenu | L'URI résultant est envoyé au Gestionnaire de contenu pour traitement. détails ...
last|L | Arrête le processus de réécriture immédiatement et n'applique plus aucune règle. Prêtez une attention particulière aux mises en garde concernant les contextes de niveau répertoire et .htaccess (voir aussi le drapeau END). détails ...
next|N | Réexécute le processus de réécriture à partir de la première règle, en utilisant le résultat du jeu de règles, sous réserve qu'il y ait un point de départ. détails ...
nocase|NC | Rend la comparaison entre modèles insensible à la casse. détails ...
noescape|NE | Empêche mod_rewrite d'effectuer un échappement hexadécimal des caractères spéciaux dans le résultat de la réécriture. détails ...
nosubreq|NS | La règle est sautée si la requête courante est une sous-requête interne. détails ...
proxy|P | Force l'envoi en interne de l'URL de substitution en tant que requête mandataire. détails ...
passthrough|PT | L'URI résultant est repassé au moteur de mise en correspondance des URLs pour y être traité par d'autres traducteurs URI-vers-nom de fichier, comme Alias ou Redirect. détails ...
qsappend|QSA | Ajoute toute chaîne de paramètres présente dans l'URL de la requête originale à toute chaîne de paramètres créée dans la cible de réécriture. détails ...
qsdiscard|QSD | Supprime toute chaîne de paramètres de l'URI entrant. détails ...
qslast|QSL | Interprète le dernier (le plus à droite) point d'interrogation comme le délimiteur de la chaîne de paramètres de la requête, au lieu du premier (le plus à gauche) comme c'est le cas habituellement. Disponble à partir de la version 2.4.19 du serveur HTTP Apache. détails ...
redirect|R[=code] | Force une redirection externe, avec un code de statut HTTP optionnel. détails ...
skip|S=nombre | Si la règle courante s'applique, le moteur de réécriture doit sauter les nombre règles suivantes. détails ...
type|T=MIME-type | Force l'attribution du Type-MIME spécifié au fichier cible. détails ...

Développement du répertoire home

Quand la chaîne de substitution commence par quelque chose comme "/~user" (de manière explicite ou par références arrières), mod_rewrite développe le répertoire home sans tenir compte de la présence ou de la configuration du module mod_userdir.

Ce développement n'est pas effectué si le drapeau PT est utilisé dans la directive RewriteRule

Voici toutes les combinaisons de substitution et leurs significations :

Dans la configuration au niveau du serveur principal (httpd.conf)
pour la requête ``GET /chemin/infochemin'':

Règle | Résultat de la substitution
^/un_chemin(.*) autre_chemin$1 | invalide, non supporté
^/un_chemin(.*) autre_chemin$1 [R] | invalide, non supporté
^/un_chemin(.*) autre_chemin$1 [P] | invalide, non supporté
^/un_chemin(.*) /autre_chemin$1 | /autre_chemin/info_chemin
^/un_chemin(.*) /autre_chemin$1 [R] | http://cet_hote/autre_chemin/info_chemin via une redirection externe
^/un_chemin(.*) /autre_chemin$1 [P] | sans objet, non supporté
^/un_chemin(.*) http://cet_hote/autre_chemin$1 | /autre_chemin/info_chemin
^/un_chemin(.*) http://cet_hote/autre_chemin$1 [R] | http://cet_hote/autre_chemin/info_chemin via une redirection externe
^/un_chemin(.*) http://cet_hote/autre_chemin$1 [P] | sans objet, non supporté
^/un_chemin(.*) http://autre_hote/autre_chemin$1 | http://autre_hote/autre_chemin/info_chemin via une redirection externe
^/un_chemin(.*) http://autre_hote/autre_chemin$1 [R] | http://autre_hote/autre_chemin/info_chemin (le drapeau [R] est redondant)
^/somepath(.*) http://otherhost/otherpath$1 [P] | http://otherhost/otherpath/pathinfo via internal proxy

Dans une configuration de niveau répertoire pour /chemin
(/chemin/physique/vers/chemin/.htacccess, avec RewriteBase "/chemin")
pour la requête ``GET /chemin/chemin-local/infochemin'':

Règle | Résultat de la substitution
^chemin-local(.*) autre-chemin$1 | /chemin/autre-chemin/infochemin
^chemin-local(.*) autre-chemin$1 [R] | http://cet-hôte/chemin/autre-chemin/infochemin via redirection externe
^chemin-local(.*) autre-chemin$1 [P] | n'a pas lieu d'être, non supporté
^chemin-local(.*) /autre-chemin$1 | /autre-chemin/infochemin
^chemin-local(.*) /autre-chemin$1 [R] | http://cet-hôte/autre-chemin/infochemin via redirection externe
^chemin-local(.*) /autre-chemin$1 [P] | n'a pas lieu d'être, non supporté
^chemin-local(.*) http://cet-hôte/autre-chemin$1 | /autre-chemin/infochemin
^chemin-local(.*) http://cet-hôte/autre-chemin$1 [R] | http://cet-hôte/autre-chemin/infochemin via redirection externe
^chemin-local(.*) http://cet-hôte/autre-chemin$1 [P] | n'a pas lieu d'être, non supporté
^chemin-local(.*) http://autre hôte/autre-chemin$1 | http://autre hôte/autre-chemin/infochemin via redirection externe
^chemin-local(.*) http://autre hôte/autre-chemin$1 [R] | http://autre hôte/autre-chemin/infochemin via redirection externe (le drapeau [R] est redondant)
^chemin-local(.*) http://autre hôte/autre-chemin$1 [P] | http://autre hôte/autre-chemin/infochemin via un mandataire interne


Introduction au module Apache mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Introduction au module Apache mod_rewrite

Ce document est un complément à la documentation de référence du module mod_rewrite. Il décrit les concepts de base dont la connaissance est nécessaire pour l'utilisation de mod_rewrite. D'autres documents entrent d'avantage dans les détails, mais celui-ci devrait aider le débutant à se mouiller les pieds.

Voir aussi

  • Documentation du module mod_rewrite
  • Redirection and remise en correspondance
  • Contrôle d'accès
  • Serveurs virtuels
  • Mise en cache
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

Introduction

Le module Apache mod_rewrite est un module puissant et sophistiqué qui permet la réécriture des URLs. Grâce à lui, vous pouvez effectuer quasiment tous les types de réécriture d'URLs dont vous avez besoin. Il est cependant assez complexe, et peut paraître intimidant au débutant. Certains ont aussi tendance à traiter les règles de réécriture comme des incantations magiques, et à les utiliser sans vraiment comprendre leur manière d'agir.

Ce document a pour ambition d'être suffisamment explicite pour permettre la compréhension, et non la copie en aveugle, de ce qui suit.

Gardez à l'esprit que de nombreuses tâches de manipulation d'URLs courantes n'ont pas besoin de la puissance et de la complexité de mod_rewrite. Pour les tâches simples, voir mod_alias et la documentation sur la Mise en correspondance des URLs avec le système de fichiers.

Enfin, avant de procéder, assurez-vous d'avoir configuré le niveau de journalisation de mod_rewrite à un des niveaux de trace via la directive LogLevel. Bien que ceci risque de vous submerger sous une énorme quantité d'informations, le débogage des problèmes avec la configuration de mod_rewrite est à ce prix car vous verrez alors exactement comment chaque règle est traitée.

Expressions rationnelles

mod_rewrite utilise le vocabulaire des Expressions rationnelles compatibles Perl. Ce document n'a pas pour prétention d'être une référence détaillée des expressions rationnelles. A cet effet, nous recommandons les pages de manuel de PCRE, la page de manuel des expressions rationnelles Perl, et l'ouvrage Mastering Regular Expressions, by Jeffrey Friedl.

Dans ce document, nous avons pour but de vous fournir suffisamment de vocabulaire des expressions rationnelles pour vous mettre le pied à l'étrier, sans être dépassé, en espérant que les directives RewriteRule vous apparaîtront comme des formules scientifiques, plutôt que comme des incantations magiques.

Vocabulaire des expressions rationnelles

Vous trouverez dans ce qui suit le minimum à connaître pour être en mesure d'écrire des expressions rationnelles et des règles RewriteRule. Ceci ne représente certainement pas un vocabulaire des expressions rationnelles complet, mais constitue un bon point de départ, et devrait vous aider à déchiffrer les expressions rationnelles simples, et à écrire vos propres expressions.

Motif | Signification | Exemple
. | Correspond à tout caractère unique | c.t correspondra à cat, cot, cut, etc.
+ | Répète le caractère de correspondance précédent une ou plusieurs fois | a+ correspond à a, aa, aaa, etc.
* | Répète le caractère de correspondance précédent zéro ou plusieurs fois | a* correspond à tout ce à quoi correspond a+, mais correspond aussi à la chaîne vide.
? | Rend la correspondance optionnelle. | colou?r correspondra à color et colour.
^ | Appelé ancrage, correspond au début de la chaîne | ^a correspond à une chaîne qui commence par a
$ | L'autre ancrage, correspond à la fin de la chaîne. | a$ correspond à une chaîne qui se termine par a.
( ) | Regroupe plusieurs caractères en une seule entité, et conserve une correspondance à des fins d'utilisation dans une référence arrière. | (ab)+ correspond à ababab - à savoir, le + s'applique au groupe. Pour plus de détails sur les références arrières, voir ci-dessous.
[ ] | Une classe de caractères - correspond à un des caractères de la classe | c[uoa]t correspond à cut, cot ou cat.
[^ ] | Négation de la classe de caractères - correspond à tout caractère ne faisant pas partie de la classe | c[^/]t correspond à cat ou c=t mais pas à c/t

Avec mod_rewrite, le caractère ! peut préfixer une expression rationnelle afin d'en exprimer la négation. Autrement dit, une chaîne ne correspondra que si elle ne correspond pas à l'expression située après le !.

Disponibilité des références arrières dans les expressions rationnelles

Vous devez vous souvenir d'une chose importante : chaque fois que vous utilisez des parenthèses dans un Modèle ou dans un des modèles de conditions, des références arrières sont créées en interne et peuvent être rappelées via les chaînes $N et %N (voir ci-dessous). Ces références sont disponibles lors de la création de la chaîne de substitution d'une directive RewriteRule ou de la chaîne de test d'une directive RewriteCond.

Les captures dans les modèles de directives RewriteRule sont paradoxalement disponibles dans toutes les directives RewriteCond qui précèdent, car les expressions des directives RewriteRule sont évaluées avant les conditions individuelles.

La figure 1 montre à quels endroits les références arrières sont suceptibles d'être développées, et illustre le flux des comparaisons effectuées par les règles RewriteRule et RewriteCond. Dans les chapitres suivants, nous examinerons comment utiliser ces références arrières, donc ne vous affolez pas si elles vous paraissent un peu exotiques au premier abord.

Flux des comparaisons effectuées par les règles RewriteRule et RewriteCond
Figure 1 : Le cheminement d'une référence arrière à travers une règle.
Dans cet exemple, une requête pour /test/1234 serait transformée en /admin.foo?page=test&id=1234&host=admin.example.com.

Les bases des règles de réécriture

Une règle de réécriture RewriteRule est constituée de trois arguments séparés par des espaces. Les arguments sont :

  1. Modèle: le modèle des URLs auxquelles la règle doit s'appliquer;
  2. Substitution: vers quoi la requête correspondante doit être transformée;
  3. [drapeaux]: options affectant la requête réécrite.

Le Modèle est une expression rationnelle. Au sein de la première règle de réécriture, ou jusqu'à ce qu'une substitution survienne, elle est comparée au chemin de l'URL de la requête entrante (la partie située après le nom d'hôte mais avant tout point d'interrogation qui indique le début d'une chaîne de paramètres de requête) ou, dans un contexte de répertoire, au chemin de la requête relativement au répertoire pour lequel la règle est définie. Lorsqu'une substitution a eu lieu, les règles suivantes effectuent leurs comparaisons par rapport à la valeur substituée.

Syntaxe de la directive RewriteRule
Figure 2 : Syntaxe de la directive RewriteRule.

La chaîne de Substitution peut, quant à elle, être de trois types :

Un chemin complet du système de fichiers vers une ressource
RewriteRule "^/jeux" "/usr/local/jeux/web"

Ceci peut faire correspondre une requête à toute localisation voulue de votre système de fichiers, un peu comme la directive Alias.

Un chemin web vers une ressource
RewriteRule "^/foo$" "/bar"

Si la directive DocumentRoot a pour valeur /usr/local/apache2/htdocs, cette règle va faire correspondre les requêtes pour http://example.com/foo au chemin /usr/local/apache2/htdocs/bar.

Une URL absolue
RewriteRule "^/produits/vues$" "http://site2.example.com/voirproduits.html" [R]

Ceci informe le client qu'il doit effectuer une nouvelle requête vers l'URL spécifiée.

La chaîne de Substitution peut aussi contenir des références arrières vers des parties du chemin d'URL entrant correspondant au Modèle. Considérons ce qui suit :

RewriteRule "^/produits/(.*)/view$" "/var/web/produitsdb/$1"

La variable $1 sera remplacée par tout texte correspondant à l'expression située entre les parenthèses dans le Modèle. Par exemple, une requête pour http://example.com/produits/r14df/vue correspondra au chemin /var/web/produitsdb/r14df.

S'il y a plus d'une expression entre parenthèses, elle seront accessibles selon leur ordre d'apparition via les variables $1, $2, $3, etc...

Drapeaux de réécriture

Le comportement d'une règle RewriteRule peut être modifié par la présence d'un ou plusieurs drapeaux en fin de règle. Par exemple, les conditions de correspondance d'une règle peuvent être rendues insensibles à la casse par la présence du drapeau [NC] :

RewriteRule "^puppy.html" "petitchien.html" [NC]

Pour une liste des drapeaux disponibles, leurs significations, et des exemples, voir le document Drapeaux de réécriture.

Conditions de réécriture

Il est possible d'utiliser une ou plusieurs directives RewriteCond pour restreindre les types de requêtes auxquelles devra s'appliquer la règle RewriteRule suivante. Le premier argument est une variable décrivant une caractéristique de la requête, le second argument est une expression rationnelle qui doit correspondre à la variable, et un troisième argument optionnel est une liste de drapeaux qui modifient la manière dont la correspondance est évaluée.

Syntaxe de la directive RewriteCond
Figure 3 : Syntaxe de la directive RewriteCond

Par exemple, pour renvoyer toutes les requêtes en provenance d'une certaine tranche d'adresses IP vers un autre serveur, vous pouvez utiliser :

RewriteCond "%{REMOTE_ADDR}" "^10\.2\."
RewriteRule "(.*)" "http://intranet.example.com$1"

Si vous spécifiez plus d'une directive RewriteCond, ces directives doivent toutes être satisfaites pour que la règle RewriteRule suivante s'applique. Par exemple, pour interdire les requêtes qui contiennent le mot "hack" dans la chaîne de requête, sauf si elles contiennent aussi un cookie contenant le mot "go", vous pouvez utiliser :

RewriteCond "%{QUERY_STRING}" "hack"
RewriteCond "%{HTTP_COOKIE}" "!go"
RewriteRule "." "-" [F]

Notez que le point d'exclamation indique une correspondance négative ; ainsi, la règle n'est appliquée que si le cookie ne contient pas "go"

Les correspondances dans les expressions rationnelles contenues dans les directives RewriteCond peuvent constituer des parties de la chaîne de Substitution de la règle RewriteRule via les variables %1, %2, etc... Par exemple, ce qui suit va diriger la requête vers un répertoire différent en fonction du nom d'hôte utilisé pour accéder au site :

RewriteCond "%{HTTP_HOST}" "(.*)"
RewriteRule "^/(.*)" "/sites/%1/$1"

Si la requête concernait http://example.com/foo/bar, alors %1 contiendrait example.com et $1 contiendrait foo/bar.

Tables de réécriture

La directive RewriteMap permet en quelque sorte de faire appel à une fonction externe pour effectuer la réécriture à votre place. Tout ceci est décrit plus en détails dans la Documentation supplémentaire sur RewriteMap.

Fichiers .htaccess

La réécriture est en général définie au niveau de la configuration du serveur principal (en dehors de toute section <Directory>) ou dans une section <VirtualHost>. Il s'agit là de la manière la plus simple de mettre en oeuvre la réécriture et nous la recommandons. Il est possible, cependant, de mettre en oeuvre la réécriture au sein d'une section <Directory> ou d'un fichier .htaccess ; ce type de configuration est cependant plus complexe. Cette technique est appelée réécriture par répertoire.

La principale différence avec les réécritures au niveau du serveur réside dans le fait que le préfixe du chemin du répertoire contenant le fichier .htaccess est supprimé avant la mise en correspondance dans la règle RewriteRule. De plus, on doit utiliser la directive RewriteBase pour s'assurer que la requête est correctement mise en correspondance.


Redirection et remise en correspondance avec mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Redirection et remise en correspondance avec mod_rewrite

Ce document est un complément à la Documentation de référence de mod_rewrite. Il montre comment utiliser mod_rewrite pour rediriger et remettre en correspondance une requête. Il contient de nombreux exemples d'utilisation courante de mod_rewrite avec une description détaillée de leur fonctionnement.

Vous devez vous attacher à comprendre le fonctionnement des exemples, car la plupart d'entre eux ne fonctionneront pas sur votre système si vous vous contentez de les copier/coller dans vos fichiers de configuration.

Voir aussi

  • Documentation du module mod_rewrite
  • Introduction à mod_rewrite
  • Contrôler l'accès
  • Serveurs virtuels
  • Serveurs mandataires
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

De l'ancienne à la nouvelle URL (en interne)

Description :

Supposons que nous ayons récemment renommé la page foo.html en bar.html, et voulions maintenant que l'ancienne URL soit toujours valide à des fins de compatibilité ascendante. En fait, on voudrait que le changement de nom soit transparent aux utilisateurs de l'ancienne URL.

Solution :

On réécrit l'ancienne URL en interne vers la nouvelle via la règle suivante :

RewriteEngine  on
RewriteRule    "^/foo\.html$" "/bar.html" [PT]

De l'ancien au nouveau (en externe)

Description :

Supposons toujours que nous ayons récemment renommé la page foo.html en bar.html, et voulions maintenant que l'ancienne URL soit toujours valide à des fins de compatibilité ascendante. En revanche, nous voulons cette fois que la nouvelle URL soit suggérée aux utilisateurs de l'ancienne URL, c'est à dire que l'adresse vue depuis leur navigateur doit également être modifiée.

Solution :

On force une redirection HTTP vers la nouvelle URL, ce qui entraîne une modification de celle du navigateur et aussi de ce que voit l'utilisateur :

RewriteEngine  on
RewriteRule    "^foo\.html$"  "bar.html"  [R]
Discussion

Dans l'exemple interne, on a utilisé mod_rewrite afin de dissimuler la redirection au client. Dans cet exemple, en revanche, on aurait pu se contenter d'une directive Redirect :

Redirect "/foo.html" "/bar.html"

Ressource déplacée vers un autre serveur

Description :

Si une ressource a été déplacée vers un autre serveur, vous pouvez faire en sorte que les URLs de l'ancien serveur continuent de fonctionner pendant un certain temps, afin de laisser au utilisateurs le temps de modifier leurs favoris.

Solution :

Vous pouvez utiliser mod_rewrite pour rediriger ces URLs vers le nouveau serveur, mais vous pouvez aussi utiliser les directives Redirect ou RedirectMatch.

#Avec mod_rewrite
RewriteEngine on
RewriteRule   "^/docs/(.+)"  "http://nouveau.example.com/docs/$1"  [R,L]
#Avec RedirectMatch
RedirectMatch "^/docs/(.*)" "http://nouveau.example.com/docs/$1"
#Avec Redirect
Redirect "/docs/" "http://nouveau.example.com/docs/"

De statique à dynamique

Description :

Comment transformer une page statique foo.html en sa variante dynamique foo.cgi de manière transparente, c'est à dire sans en avertir le navigateur/utilisateur.

Solution :

On réécrit simplement l'URL en script CGI et force le gestionnaire de contenu à cgi-script de façon à ce que le script s'exécute en tant que programme CGI. Ainsi, une requête vers /~quux/foo.html conduit en interne à l'invocation de /~quux/foo.cgi.

RewriteEngine  on
RewriteBase    "/~quux/"
RewriteRule    "^foo\.html$"  "foo.cgi"  [H=cgi-script]

Compatibilité ascendante dans le cadre d'une modification d'extension de nom de fichier

Description :

Comment conférer une compatibilité ascendante aux URLs (existant encore virtuellement) après avoir migré document.YYYY vers document.XXXX, c'est à dire après avoir par exemple traduit un lot de fichiers .html en fichiers .php ?

Solution :

On réécrit simplement le nom du fichier en son nom de base et vérifie s'il existe aussi avec la nouvelle extension. Si c'est le cas, on utilise ce nom, sinon on réécrit l'URL sous sa forme originale.

#   jeu de règles assurant une compatibilité ascendante en réécrivant

#   document.html en document.php si et seulement si document.php

#   existe
<Directory "/var/www/htdocs">
    RewriteEngine on
    RewriteBase "/var/www/htdocs"

    RewriteCond "$1.php" -f
    RewriteCond "$1.html" !-f
    RewriteRule "^(.*).html$" "$1.php"
</Directory>
Discussion

Cet exemple utilise une fonctionnalité souvent méconnue de mod_rewrite, en tirant avantage de l'ordre d'exécution du jeu de règles. En particulier, mod_rewrite évalue la partie gauche des règles de réécriture avant d'évaluer les directives RewriteCond. En conséquence, $1 est déjà défini au moment où les directives RewriteCond sont évaluées. Ceci nous permet de tester l'existence du fichier original (document.html) et du fichier cible (document.php) en utilisant le même nom de base.

Ce jeu de règles est conçu pour une utilisation dans un contexte de répertoire (au sein d'une section <Directory> ou d'un fichier .htaccess), de façon à ce que les vérifications -f effectuent leurs recherches dans le bon répertoire. Vous serez peut-être amené à définir une directive RewriteBase pour spécifier le répertoire de base à partir duquel vous travaillez.

Noms d'hôtes canoniques

Description :
Le but de cette règle est de préférer l'utilisation d'un nom d'hôte particulier à d'autres noms d'hôte utilisables pour atteindre le même site. Par exemple, si vous voulez utiliser www.example.com à la place de example.com, vous pouvez utiliser une solution du style :
Solution :

Pour y parvenir, il vaut mieux se passer de mod_rewrite, et utiliser plutôt la directive Redirect dans une section de serveur virtuel pour le/les noms d'hôte non canoniques.

<VirtualHost *:80>
  ServerName undesired.example.com
  ServerAlias example.com notthis.example.com

  Redirect "/" "http://www.example.com/"
</VirtualHost>

<VirtualHost *:80>
  ServerName www.example.com
</VirtualHost>

Vous pouvez aussi utiliser la directive <If> :

<If "%{HTTP_HOST} != 'www.example.com'">
    Redirect "/" "http://www.example.com/"
</If>

Ou, par exemple, pour rediriger une portion de votre site vers HTTPS :

<If "%{SERVER_PROTOCOL} != 'HTTPS'">
    Redirect "/admin/" "https://www.example.com/admin/"
</If>

Si, pour une raison particulière, vous voulez tout de même utiliser mod_rewrite - dans le cas, par exemple, où vous avez besoin d'un jeu plus important de règles de réécritures - vous pouvez utiliser la recette suivante :

Pour les sites écoutant sur un port autre que 80:

RewriteCond "%{HTTP_HOST}"   "!^www\.example\.com" [NC]
RewriteCond "%{HTTP_HOST}"   "!^$"
RewriteCond "%{SERVER_PORT}" "!^80$"
RewriteRule "^/?(.*)"         "http://www.example.com:%{SERVER_PORT}/$1" [L,R,NE]

Et pour un site écoutant sur le port 80

RewriteCond "%{HTTP_HOST}"   "!^www\.example\.com" [NC]
RewriteCond "%{HTTP_HOST}"   "!^$"
RewriteRule "^/?(.*)"         "http://www.example.com/$1" [L,R,NE]

Si vous souhaitez que cette règle s'applique à tous les noms de domaine - en d'autres termes, si vous voulez rediriger example.com vers www.example.com pour toutes les valeurs possibles de example.com, vous pouvez utiliser le jeu de règles suivants :

RewriteCond "%{HTTP_HOST}" "!^www\." [NC]
RewriteCond "%{HTTP_HOST}" "!^$"
RewriteRule "^/?(.*)" "http://www.%{HTTP_HOST}/$1" [L,R,NE]

Vous pouvez utiliser ce jeu de règles aussi bien dans le fichier de configuration de votre serveur principal que dans un fichier .htaccess placé dans le répertoire défini par la directive DocumentRoot du serveur.

Recherche de pages dans plus d'un répertoire

Description:

Une ressource peut exister dans plusieurs répertoires, et nous voulons rechercher cette ressource dans ces répertoires lorsqu'elle fait l'objet d'une requête. Il est possible que nous ayons récemment réorganisé la structure de notre site en répartissant son contenu dans plusieurs répertoires.

Solution :

Le jeu de règles suivant recherche la ressource dans deux répertoires, et s'il ne la trouve dans aucun des deux, il tentera simplement de la servir à partir de l'adresse fournie dans la requête.

RewriteEngine on

#   on cherche tout d'abord dans dir1/...
#   ... et si on trouve, on est content et on arrête :
RewriteCond         "%{DOCUMENT_ROOT}/dir1/%{REQUEST_URI}"  -f
RewriteRule  "^(.+)"  "%{DOCUMENT_ROOT}/dir1/$1"  [L]

#   on cherche ensuite dans dir2/...
#   ... et si on trouve, on est content et on arrête :
RewriteCond         "%{DOCUMENT_ROOT}/dir2/%{REQUEST_URI}"  -f
RewriteRule  "^(.+)"  "%{DOCUMENT_ROOT}/dir2/$1"  [L]

#   sinon, on continue la recherche avec d'autres directives Alias
#   ou ScriptAlias, etc...
RewriteRule   "^"  "-"  [PT]

Redirection vers des serveurs géographiquement distribués

Description :

Notre site web possède de nombreux miroirs, et nous voulons rediriger les utilisateurs vers celui qui se situe dans le pays où ils se trouvent.

Solution :

En consultant le nom d'hôte du client demandeur, on détermine le pays dans lequel il se trouve. S'il est impossible d'effectuer une recherche sur leur adresse IP, on se rabat sur un serveur par défaut.

Nous allons utiliser une directive RewriteMap afin de construire une liste des serveurs que nous voulons utiliser.

HostnameLookups on
RewriteEngine on
RewriteMap    multiplex         "txt:/path/to/map.mirrors"
RewriteCond  "%{REMOTE_HOST}"     "([a-z]+)$ [NC]"
RewriteRule   "^/(.*)$"  "${multiplex:%1|http://www.example.com/}$1"  [R,L]

## liste_miroirs -- Table de correspondance pays - serveurs

de http://www.exemple.de/
uk http://www.exemple.uk/
com http://www.example.com/
##EOF##

Discussion
Ce jeu de règles nécessite la définition à on de la directive HostNameLookups, ce qui peut induire une baisse de performance significative.

La directive RewriteCond extrait la dernière partie du nom d'hôte du client demandeur - le code du pays - et la règle de réécriture qui suit utilise cette valeur pour rechercher le serveur miroir approprié dans le fichier de correspondances.

Contenu dépendant du navigateur

Description :

Nous voulons fournir des contenus différents en fonction du navigateur (user-agent) qui effectue la requête.

Solution :

Nous devons déterminer quel contenu servir, en nous basant sur l'en-tête HTTP "User-Agent". La configuration suivante effectue ceci : si l'en-tête HTTP "User-Agent" commence par "Mozilla/3", le nom de la page foo.html est réécrit en foo.NS.html et la réécriture s'arrête. Si le navigateur est "Lynx" ou "Mozilla" version 1 ou 2, l'URL devient foo.20.html. Tous les autres navigateurs reçoivent la page foo.32.html. Tout ceci est effectué par le jeu de règles suivant :

RewriteCond "%{HTTP_USER_AGENT}"  "^Mozilla/3.*"
RewriteRule "^foo\.html$"         "foo.NS.html"          [L]

RewriteCond "%{HTTP_USER_AGENT}"  "^Lynx/" [OR]
RewriteCond "%{HTTP_USER_AGENT}"  "^Mozilla/[12]"
RewriteRule "^foo\.html$"         "foo.20.html"          [L]

RewriteRule "^foo\.html$"         "foo.32.html"          [L]

URLs canoniques

Description :

Sur certains serveurs, une ressource peut posséder plusieurs URLs. Il y a en général les URLs canoniques (celles qui sont réellement distribuées et utilisées), et celles qui correspondent à des raccourcis, les URLs internes, etc... Quelle que soit l'adresse que l'utilisateur fournit dans la requête, il devrait finalement voir l'URL canonique dans la barre d'adresse de son navigateur.

Solution :

Nous effectuons une redirection HTTP externe pour toutes les URLs non canoniques afin de les corriger dans la barre d'adresse du navigateur, et ceci pour toutes les requêtes futures. Dans le jeu de règles suivant, nous remplaçons /matous et /minettes par le canonique /chats.

RewriteRule   "^/(matous|minettes)/(.*)"    "/chats/$2"  [R]
Discussion :
On serait mieux inspiré d'utiliser ici les directives Redirect ou RedirectMatch :
RedirectMatch "^/(matous|minettes)/(.*)" "/chats/$2"

Déplacement du répertoire DocumentRoot

Description :

En général, le répertoire DocumentRoot du serveur web correspond à l'URL "/". Ce répertoire ne contient cependant pas forcément des ressources de première importance pour l'utilisateur. Par exemple, vous préférerez peut-être que le répertoire d'accueil d'un visiteur accédant pour la première fois à votre site soit un répertoire particulier /a-propos-de/. Pour y parvenir, utilisez le jeu de règles suivant :

Solution :

On redirige l'URL / vers /a-propos-de/ :

RewriteEngine on
RewriteRule   "^/$"  "/a-propos-de/"  [R]

Notez que l'on peut aussi y parvenir en utilisant la directive RedirectMatch :

RedirectMatch "^/$" "http://example.com/a-propos-de/"

Notez aussi que cet exemple ne réécrit que l'URL racine. En d'autres termes, il réécrit une requête pour http://example.com/, mais pas pour une requête http://example.com/page.html. Si vous avez effectivement modifié la racine de vos documents - c'est à dire si tous vos contenus se trouvent dans un sous-répertoire, il est largement préférable de modifier simplement votre directive DocumentRoot, ou de déplacer l'ensemble du contenu vers le répertoire supérieur, plutôt que de réécrire les URLs.

Ressource par défaut

Description :
Vous voulez qu'une seule ressource (disons un certain fichier tel que index.php) soit servie pour toutes les requêtes à destination d'un certain répertoire, sauf pour celles qui concernent une ressource existant effectivement comme une image, ou un fichier css.
Solution :

Depuis la version 2.2.16, vous pouvez y parvenir via la directive FallbackResource :

<Directory "/var/www/my_blog">
  FallbackResource "index.php"
</Directory>

Cependant, si vos besoins étaient plus complexes, vous pouviez, dans les versions plus anciennes d'Apache, utiliser un jeu de règles du style :

<Directory "/var/www/my_blog">
  RewriteBase "/my_blog"

  RewriteCond "/var/www/my_blog/%{REQUEST_FILENAME}" !-f
  RewriteCond "/var/www/my_blog/%{REQUEST_FILENAME}" !-d
  RewriteRule "^" "index.php" [PT]
</Directory>

D'autre part, si vous voulez transmettre l'URI de la requête en tant que chaîne de paramètres à index.php, vous pouvez remplacer cette règle de réécriture par :

RewriteRule "(.*)" "index.php?$1" [PT,QSA]

Notez que l'on peut utiliser ces jeux de règles aussi bien dans un fichier .htaccess que dans une section <Directory>.

Rewrite query string

Description :
Vous voulez extraire une valeur particulière d'une chaîne de paramètres d'une URL, et soit la remplacer, soit l'incorporer dans un autre composant de l'URL.
Solutions :

Dans la plupart des solutions de cette section, on utilise la même condition qui stocke la valeur recherchée dans la référence arrière %2. %1 est le début de la requête, et %3 ce qui reste. Cette condition est un peu complexe car elle introduit de la flexibilité et évite les doubles perluettes '&&' dans les substitutions.

  • Cette solution supprime le couple clé/valeur recherché :
    # Remove mykey=???
RewriteCond "%{QUERY_STRING}" "(.*(?:^|&))mykey=([^&]*)&?(.*)&?$"
RewriteRule "(.*)" "$1?%1%3"
  • Cette solution remplace la partie de l'URL qui suit la valeur recherchée par un '?' :
    # Copy from query string to PATH_INFO
RewriteCond "%{QUERY_STRING}" "(.*(?:^|&))mykey=([^&]*)&?(.*)&?$"
RewriteRule "(.*)" "$1/products/%2/?" [PT]
  • Cette solution utilise la valeur recherchée dans une deuxième condition ::
    # Capture the value of mykey in the query string
RewriteCond "%{QUERY_STRING}" "(.*(?:^|&))mykey=([^&]*)&?(.*)&?$""
RewriteCond "%2" !=not-so-secret-value
RewriteRule "(.*)" - [F]
  • Cette solution produit l'effet inverse des précédentes ; elle copie des composantes du chemin (peut-être PATH_INFO) depuis l'URL vers sa chaîne de paramètres :
    # The desired URL might be /products/kitchen-sink, and the script expects
# /path?products=kitchen-sink.
RewriteRule "^/?path/([^/]+)/([^/]+)" "/path?$1=$2" [PT]


Utiliser mod_rewrite pour le contrôle d'accès - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Utiliser mod_rewrite pour le contrôle d'accès

Ce document est un complément à la documentation de référence de mod_rewrite. Il explique comment utiliser mod_rewrite pour contrôler l'accès à diverses ressources, ainsi que d'autres techniques en rapport. Il contient de nombreux exemples d'utilisation courante de mod_rewrite avec une description détaillée de leur fonctionnement.

Vous devez vous attacher à comprendre le fonctionnement des exemples, car la plupart d'entre eux ne fonctionneront pas sur votre système si vous vous contentez de les copier/coller dans vos fichiers de configuration.

Voir aussi

  • Documentation du module mod_rewrite
  • Introduction à mod_rewrite
  • Redirection et remise en correspondance
  • Serveurs virtuels
  • Serveurs mandataires
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

Blocage du référencement à chaud (Hotlinking) d'images

Description :

Cette technique vous permet d'interdire à d'autres sites d'inclure directement vos images dans leurs pages. On fait souvent référence à cette pratique sous le nom de référencement à chaud (Hotlinking) qui entraîne l'utilisation de votre bande passante pour servir des contenus faisant partie du site de quelqu'un d'autre.

Solution :

Cette technique repose sur la valeur de la variable optionnelle HTTP_REFERER. Certaines personnes pourront donc contourner cette limitation. Pour la plupart des utilisateurs cependant, la requête échouera, en ce sens que l'image ne sera pas affichée depuis le site tiers.

Il y a plusieurs manières de gérer cette situation.

Dans le premier exemple, nous rejetons tout simplement la requête si elle ne provenait pas d'une page appartenant à notre site. Pour les besoins de cet exemple, nous supposons que le nom de votre site est www.example.com.

RewriteCond "%{HTTP_REFERER}" "!^$"
RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
RewriteRule "\.(gif|jpg|png)$"    "-"   [F,NC]

Dans le second exemple, plutôt que de rejeter la requête, nous affichons une autre image à la place.

RewriteCond "%{HTTP_REFERER}" "!^$"
RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
RewriteRule "\.(gif|jpg|png)$"    "/images/go-away.png"   [R,NC]

Dans le troisième exemple, nous redirigeons la requête vers une image appartenant à un autre site.

RewriteCond "%{HTTP_REFERER}" "!^$"
RewriteCond "%{HTTP_REFERER}" "!www.example.com" [NC]
RewriteRule "\.(gif|jpg|png)$" "http://other.example.com/image.gif"   [R,NC]

De tous ces exemples, les deux derniers semblent les plus efficaces pour faire en sorte que les gens arrêtent de référencer vos images à chaud, car il ne verront pas les images qu'ils s'attendent à voir.

Discussion :

Si vous ne voulez pas rediriger la requête, mais simplement interdire l'accès à la ressource, vous pouvez y parvenir sans utiliser mod_rewrite :

SetEnvIf Referer "example\.com" localreferer
<FilesMatch "\.(jpg|png|gif)$">
    Require env localreferer
</FilesMatch>

Blocage des robots

Description :

Dans cet exemple, nous allons discuter d'une méthode permettant de bloquer les requêtes persistentes en provenance d'un robot particulier, ou d'un navigateur.

La méthode classique pour exclure un robot consiste à définir un fichier, /robots.txt qui spécifie les parties de votre site web pour lesquelles vous voulez exclure les robots. Malheureusement, certains robots ne tiennent pas compte de ces fichiers.

Notez qu'il existe des méthodes d'exclusion qui n'utilisent pas mod_rewrite. Notez aussi que toute technique qui repose sur le contenu de la chaîne client USER_AGENT peut être contournée très facilement car cette chaîne peut être modifiée.

Solution :

On utilise un jeu de règles qui spécifie le répertoire à protéger, ainsi que la chaîne client USER_AGENT qui identifie le robot malin ou envahissant.

Dans cet exemple, nous bloquons un robot nommé Vilain_Robot pour le répertoire /secret/fichiers. Si vous voulez bloquer ce client seulement depuis une source particulière, vous pouvez aussi spécifier un intervalle d'adresses IP.

RewriteCond "%{HTTP_USER_AGENT}"   "^NameOfBadRobot"
RewriteCond "%{REMOTE_ADDR}"       "=123\.45\.67\.[8-9]"
RewriteRule "^/secret/files/"   "-"   [F]
Discussion :

Vous pouvez cependant parvenir au même résultat sans utiliser mod_rewrite via la méthode alternative suivante :

SetEnvIfNoCase User-Agent "^NameOfBadRobot" goaway
<Location "/secret/files">
    <RequireAll>
        Require all granted
        Require not env goaway
    </RequireAll>
</Location>

Comme indiqué plus haut, il est aisé de contourner cette technique, simplement en modifiant le contenu de l'en-tête USER_AGENT. Si vous subissez une attaque en règle, vous allez devoir réfléchir à un blocage à un niveau supérieur, par exemple une règle de filtrage de votre pare-feu.

Rejet des clients contenus dans une liste noire

Description :

Nous voulons interdire l'accès à notre serveur aux clients contenus dans une liste noire similaire à hosts.deny.

Solution :
RewriteEngine on
RewriteMap    hosts-deny  "txt:/path/to/hosts.deny"
RewriteCond   "${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}" "!=NOT-FOUND" [OR]
RewriteCond   "${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}" "!=NOT-FOUND"
RewriteRule   "^"  "-"  [F]

##
## hosts.deny
##
## ATTENTION! Ceci est une table de correspondances, non une liste,
## même si elle est traitée comme telle. mod_rewrite
## l'interprète comme une liste de paires clé/valeur, et
## chaque entrée doit au moins posséder une valeur par
## défaut "-".

193.102.180.41 -
bsdti1.sdm.de -
192.76.162.40 -

Discussion :

La seconde condition RewriteCond présuppose que HostNameLookups est défini à On, de façon à ce que les adresses IP des clients puissent être résolues. Dans le cas contraire, vous devez supprimer la seconde condition, ainsi que le drapeau [OR] de la première.

Aiguillage basé sur l'en-tête Referer

Description :

Redirige les requêtes en fonction du Referer de provenance de la requête, avec des cibles différentes pour chaque Referer.

Solution :

Le jeu de règles suivant utilise un fichier de correspondances pour associer chaque Referer à une cible de redirection.

RewriteMap  deflector "txt:/path/to/deflector.map"

RewriteCond "%{HTTP_REFERER}" !=""
RewriteCond "${deflector:%{HTTP_REFERER}}" "=-"
RewriteRule "^" "%{HTTP_REFERER}" [R,L]

RewriteCond "%{HTTP_REFERER}" !=""
RewriteCond "${deflector:%{HTTP_REFERER}|NOT-FOUND}" "!=NOT-FOUND"
RewriteRule "^" "${deflector:%{HTTP_REFERER}}" [R,L]

Le fichier de correspondances contient les cibles de redirection associées à chaque Referer, ou, si nous voulons simplement rediriger les requêtes vers leur Referer, un "-" est inscrit dans le fichier de correspondances :

##
##  deflector.map
##

http://badguys.example.com/bad/index.html    -
http://badguys.example.com/bad/index2.html   -
http://badguys.example.com/bad/index3.html   http://somewhere.example.com/


Hébergement virtuel de masse avec mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Hébergement virtuel de masse avec mod_rewrite

Ce document est un complément à la documentation de référence du module mod_rewrite. Il décrit comment créer des serveurs virtuels dynamiquement configurés en utilisant mod_rewrite.

L'utilisation de mod_rewrite n'est pas la meilleure méthode pour configurer des serveurs virtuels. Vous devez dans un premier temps tenter de résoudre votre problème via ces d'autres méthodes avant d'avoir recours à mod_rewrite. Voir aussi le document Comment éviter l'utilisation de mod_rewrite.

Voir aussi

  • Documentation du module
  • Introduction à mod_rewrite
  • Redirection et remise en correspondance
  • Contrôle d'accès
  • Serveurs mandataires
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

Serveurs virtuels pour des noms d'hôtes arbitraires

Description :

Nous voulons créer automatiquement un serveur virtuel pour tout nom d'hôte qui peut être résolu dans notre domaine, sans avoir à créer de nouvelle section VirtualHost.

Dans cet exemple, nous supposons que nous utilisons le nom d'hôte www.SITE.example.com pour chaque utilisateur, et que nous servons leur contenu depuis /home/SITE/www.

Solution :
RewriteEngine on

RewriteMap    lowercase int:tolower

RewriteCond   "${lowercase:%{HTTP_HOST}}" "^www\.([^.]+)\.example\.com$"
RewriteRule   "^(.*)" "/home/%1/www$1"
Discussion
Vous devez vérifier le bon fonctionnement de la résolution DNS - Apache ne gère pas la résolution de nom. Vous devrez créer soit des enregistrements CNAME pour chaque nom d'hôte, soit un enregistrement DNS avec caractères génériques. La création des enregistrements DNS est en dehors du sujet de ce document.

La directive RewriteMap interne tolower permet de s'assurer que les noms d'hôtes utilisés seront tous en minuscules, de façon à éviter toute ambiguité dans la structure des répertoires qui doit être créée.

Les contenus des parenthèses utilisées dans une directive RewriteCond sont enregistrés dans les références arrières %1, %2, etc..., alors que les contenus des parenthèses utilisées dans une directive RewriteRule le sont dans les références arrières $1, $2, etc...

Comme c'est le cas pour de nombreuses techniques discutées dans ce document, mod_rewrite n'est vraiment pas la meilleure méthode pour accomplir cette tâche. Vous devez plutôt vous tourner vers mod_vhost_alias, car ce dernier sera bien plus à même de gérer tout ce qui est au delà du domaine des fichiers statiques, comme les contenus dynamiques et la résolution des alias.

Configuration dynamique de serveurs virtuels via mod_rewrite

Cet extrait du fichier httpd.conf permet d'obtenir le même résultat que le premier exemple. La première moitié est très similaire à la partie correspondante ci-dessus, excepté quelques modifications requises à des fins de compatibilité ascendante et pour faire en sorte que la partie mod_rewrite fonctionne correctement ; la seconde moitié configure mod_rewrite pour effectuer le travail proprement dit.

Comme mod_rewrite s'exécute avant tout autre module de traduction d'URI (comme mod_alias), il faut lui ordonner explicitement d'ignorer toute URL susceptible d'être traitée par ces autres modules. Et comme ces règles auraient sinon court-circuité toute directive ScriptAlias, nous devons faire en sorte que mod_rewrite déclare explicitement ces correspondances.

# extrait le nom de serveur de l'en-tête Host:
UseCanonicalName Off

# journaux dissociables
LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon
CustomLog "logs/access_log" vcommon

<Directory "/www/hosts">
    # ExecCGI est nécessaire ici car on ne peut pas forcer l'exécution
    # des CGI à la manière de ScriptAlias
    Options FollowSymLinks ExecCGI
</Directory>

RewriteEngine On

# un nom de serveur extrait d'un en-tête Host: peut être dans n'importe
# quelle casse
RewriteMap  lowercase  int:tolower

## on s'occupe tout d'abord des documents normaux :

# permet à Alias "/icons/" de fonctionner - répéter pour les autres
RewriteCond  "%{REQUEST_URI}"  "!^/icons/"
# permet aux CGIs de fonctionner
RewriteCond  "%{REQUEST_URI}"  "!^/cgi-bin/"
# le coeur du traitement
RewriteRule  "^/(.*)$"  "/www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1"

## on s'occupe maintenant des CGIs - on doit forcer l'utilisation d'un
# gestionnaire
RewriteCond  "%{REQUEST_URI}"  "^/cgi-bin/"
RewriteRule  "^/(.*)$" "/www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1"  [H=cgi-script]

Utilisation d'un fichier de configuration du serveur virtuel séparé

Cette construction utilise des fonctionnalités plus avancées de mod_rewrite pour effectuer la traduction depuis le serveur virtuel vers la racine des documents, à partir d'un fichier de configuration séparé. Elle est plus souple mais nécessite une configuration plus compliquée.

Le fichier vhost.map devrait ressembler à ceci :

www.client-1.example.com /www/clients/1
www.client-2.example.com /www/clients/2
# ...
www.client-N.example.com /www/clients/N

On doit ajouter à httpd.conf :

RewriteEngine on

RewriteMap   lowercase  int:tolower

# définit le fichier de correspondances
RewriteMap   vhost      "txt:/www/conf/vhost.map"

# on s'occupe des alias comme ci-dessus
RewriteCond  "%{REQUEST_URI}"               "!^/icons/"
RewriteCond  "%{REQUEST_URI}"               "!^/cgi-bin/"
RewriteCond  "${lowercase:%{SERVER_NAME}}"  "^(.+)$"
# on effectue ici la remise en correspondance à base de fichier
RewriteCond  "${vhost:%1}"                  "^(/.*)$"
RewriteRule  "^/(.*)$"                      "%1/docs/$1"

RewriteCond  "%{REQUEST_URI}"               "^/cgi-bin/"
RewriteCond  "${lowercase:%{SERVER_NAME}}"  "^(.+)$"
RewriteCond  "${vhost:%1}"                  "^(/.*)$"
RewriteRule  "^/cgi-bin/(.*)$"              "%1/cgi-bin/$1" [H=cgi-script]


Utilisation de mod_rewrite comme mandataire - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Utilisation de mod_rewrite comme mandataire

Ce document est un complément de la documentation de référence du module mod_rewrite. Il décrit comment utiliser le drapeau [P] de la directive RewriteRule pour mandater un contenu vers un autre serveur. Plusieurs recettes décrivant des scénarios courants sont fournies.

Voir aussi

  • Documentation du module
  • Introduction à mod_rewrite
  • Redirection et remise en correspondance
  • Contrôle d'accès
  • Serveurs virtuels
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

Mandater du contenu avec mod_rewrite

Description :

mod_rewrite implémente le drapeau [P] qui permet de passer des URLs, via mod_proxy, à un autre serveur. Deux exemples sont fournis ici. Dans le premier, une URL est passée directement à un autre serveur, et servie comme si c'était une URL locale. Dans le deuxième, nous mandatons un contenu manquant vers un serveur d'arrière-plan.

Solution :

Pour passer une URL à un autre serveur, on utilise le drapeau [P] comme suit :

RewriteEngine  on
RewriteBase    "/produits/"
RewriteRule    "^widget/(.*)$"  "http://produits.example.com/widget/$1"  [P]
ProxyPassReverse "/produits/objet/" "http://produits.example.com/objet/"

Dans le deuxième exemple, nous ne mandatons la requête que si nous ne trouvons pas la ressource localement. Ceci peut s'avérer très utile lorsque vous effectuez une migration d'un serveur vers un autre, et que vous n'êtes pas certain que tout le contenu a déjà été migré.

RewriteCond "%{REQUEST_FILENAME}"       !-f
RewriteCond "%{REQUEST_FILENAME}"       !-d
RewriteRule "^/(.*)" "http://ancien.exemple.com/$1" [P]
ProxyPassReverse "/" "http://ancien.exemple.com/"
Discussion :

Dans les deux cas, on ajoute une directive ProxyPassReverse afin de s'assurer que toute redirection en provenance du serveur d'arrière-plan est renvoyée correctement au client.

Chaque fois que cela est possible, préférez l'utilisation de la directive ProxyPass ou ProxyPassMatch à mod_rewrite.


Utilisation de RewriteMap - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Utilisation de RewriteMap

Ce document est un complément à la documentation de référence du module mod_rewrite. Il décrit l'utilisation de la directive RewriteMap, et fournit des exemples pour chacun des différents types de RewriteMap.

Notez que la plupart de ces exemples ne fonctionneront pas en l'état dans le contexte de votre configuration particulière ; vous devez donc vous attacher à les comprendre, plutôt que de simplement les insérer dans votre configuration par copier/coller.

Voir aussi

  • Documentation du module mod_rewrite
  • Introduction à mod_rewrite
  • Redirection et remise en correspondance
  • Contrôle d'accès
  • Serveurs virtuels
  • Mise en cache
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

Introduction

La directive RewriteMap définit une fonction externe qui peut être appelée depuis une directive RewriteRule ou RewriteCond pour accomplir une réécriture trop compliquée, ou trop spécialisée pour être effectuée à partir d'expressions rationnelles. Vous trouverez ci-dessous les différents types disponibles pour la source de données, ceux-ci étant par ailleurs énumérés dans la documentation de référence de RewriteMap.

La syntaxe de la directive RewriteMap est la suivante :

RewriteMap MapName MapType:MapSource

L'argument MapName est un nom arbitraire que vous associez à la table de correspondances, et que vous pourrez utilisez par la suite dans les directives de réécriture. Les recherches dans la table de correspondance s'effectuent en respectant cette syntaxe :

${ nom-map : clé-recherche }
${ nom-map : clé-recherche | DefaultValue }

Lorsque cette syntaxe est employée, la table de correspondances nom-map est consultée et la clé clé-recherche recherchée. Si la clé est trouvée, la fonction de recherche dans la table de correspondance est remplacée par SubstValue, ou par DefaultValue dans le cas contraire, ou par la chaîne vide si aucune DefaultValue n'a été spécifiée.

Par exemple, vous pouvez définir une directive RewriteMap comme suit :

RewriteMap examplemap "txt:/path/to/file/map.txt"

Vous pourrez par la suite utiliser cette table de correspondances dans une directive RewriteRule comme suit :

RewriteRule "^/ex/(.*)" "${examplemap:$1}"

Il est possible de spécifier une valeur par défaut qui sera utilisée si la recherche dans la table de correspondances est infructueuse :

RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"

Contexte de répertoire et fichiers.htaccess

Vous ne pouvez utiliser la directive RewriteMap ni dans les sections <Directory>, ni dans les fichiers .htaccess. Vous devez déclarer la table de correspondances au niveau du serveur principal ou dans un contexte de serveur virtuel. En revanche, si vous ne pouvez pas déclarer la table dans une section <Directory> ou dans un fichier .htaccess, vous pourrez y faire référence dans ces contextes, une fois cette table créée.

Les sections suivantes décrivent les différents types de tables de correspondances type-map disponibles, et fournissent des exemples pour chacun d'entre eux.

int: Fonction interne

Lorsque le type-map int est spécifié, la source est une des fonctions RewriteMap internes disponibles. Les développeurs de modules peuvent fournir des fonctions internes supplémentaires en les enregistrant via l'API ap_register_rewrite_mapfunc. Les fonctions fournies par défaut sont :

  • toupper:
    Met tous les caractères de la clé en majuscules.
  • tolower:
    Met tous les caractères de la clé en minuscules.
  • escape:
    Protège les caractères spéciaux de la clé en les transformant en leur code hexadécimal.
  • unescape:
    Retraduit les codes hexadécimaux de la clé en caractères spéciaux.

Pour utiliser une de ces fonctions, créez une RewriteMap faisant référence à cette fonction int, et utilisez-la dans votre règle RewriteRule :

Redirige un URI vers son équivalent en minuscules

RewriteMap lc int:tolower
RewriteRule "(.*)" "${lc:$1}" [R]

Notez que cet exemple n'est fourni qu'à titre d'illustration, et ne constitue en aucun cas une recommandation. Si vous voulez rendre des URLs insensibles à la casse, vous devez plutôt vous tourner vers mod_speling.

txt: tables de correspondances au format texte

Lorsqu'un type-map txt est utilisé, la source-map est un chemin du système de fichiers vers un fichier de correspondances au format texte, contenant sur chaque ligne une paire clé/valeur séparées par un espace. Il est possible d'insérer des commentaires sous la forme de chaînes commençant par le caractère '#'.

Voici un exemple d'entrées valides dans un fichier de correspondances :

# Ligne de commentaires
clé valeur-substitution
clé valeur-substitution # commentaire

Lorsque la table de correspondance fait l'objet d'une recherche, la valeur spécifiée est recherchée dans le premier champ, et si elle est trouvée, la valeur de substitution est renvoyée.

Par exemple, nous pourrions utiliser un fichier de correspondances pour traduire des noms de produits en identifiants produits pour obtenir des URLs plus simples à mémoriser, en utilisant la recette suivante :

Product to ID configuration

RewriteMap product2id "txt:/etc/apache2/productmap.txt"
RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

Nous supposons ici que le script prods.php sait quoi faire lorsqu'il reçoit un argument id=NOTFOUND, dans le cas où le produit ne se trouve pas dans la table de correspondances.

Le fichier /etc/apache2/map-produit.txt contient ce qui suit :

Fichier de correspondances Produit - Identifiant

##
## map-produit.txt - Fichier de correspondances Produit - Identifiant
##

TELEVISION 993
STEREO 198
CANNE-A-PECHE 043
BALLON-BASKET 418
TELEPHONE 328

Ainsi, lorsqu'une requête pour http://example.com/produit/TELEVISION arrive, la directive RewriteRule s'applique, et la requête est transformée en interne en /prods.php?id=993.

Note: fichiers .htaccess

L'exemple donné est conçu pour être utilisé dans un contexte de serveur principal ou de serveur virtuel. Si vous voulez l'utiliser dans un fichier .htaccess, vous devrez supprimer le slash de début dans le modèle de réécriture afin que ce dernier puisse correspondre à toute URL :
RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

Recherches mises en cache

Les clés de recherche sont mises en cache par httpd jusqu'à ce que le mtime (date de modification) du fichier de correspondances soit modifié, ou que le serveur httpd soit redémarré, ce qui améliore les performances pour les tables de correspondances consultées par de nombreuses requêtes.

rnd: Fichier texte à valeurs de substitution multiples choisies de manière aléatoire

Lorsque le type-map spécifié est rnd, la source est un chemin du système de fichiers vers un fichier de correspondances au format texte dont chaque ligne contient une clé, et une ou plusieurs valeurs séparées par le caractère |. Si une clé convient, une des valeurs correspondantes sera choisie de manière aléatoire.

Par exemple, vous pouvez utiliser le fichier de correspondances et les directives suivants pour implémenter une répartition de charge aléatoire entre plusieurs serveurs d'arrière-plan, par l'intermédiaire d'un mandataire inverse. Les images sont envoyées vers un des serveurs de l'ensemble 'statique', tandis que tout le reste est envoyé vers un des serveurs de l'ensemble 'dynamique'.

Fichier de correspondances

##
## map.txt -- table de réécriture
##

statique www1|www2|www3|www4
dynamique www5|www6

Directives de configuration

RewriteMap servers "rnd:/path/to/file/map.txt"

RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
RewriteRule "^/(.*)"                "http://${servers:dynamic}/$1" [P,L]

Ainsi, lorsqu'une image est demandée et que la première règle convient, RewriteMap recherche la chaîne statique dans le fichier de correspondances qui renvoie un des noms de serveurs spécifiés de manière aléatoire, ce dernier étant utilisé dans la cible de la règle RewriteRule.

Si vous voulez qu'un des serveurs soit plus souvent sollicité que les autres (par exemple s'il possède plus de mémoire, et peut donc traiter d'avantage de requêtes), spécifiez-le plusieurs fois dans la liste des serveurs.

statique www1|www1|www2|www3|www4

dbm: Fichier condensé DBM

Lorsque le type-map dbm est utilisé, la source est un chemin du système de fichiers vers un fichier de données DBM contenant des paires clé/valeur permettant d'effectuer la correspondance. Le fonctionnement est identique à celui du type-map txt, mais beaucoup plus rapide car un fichier DBM est indexé, alors qu'un fichier texte ne l'est pas. L'accès à la clé recherchée est donc plus rapide.

Vous pouvez éventuellement spécifier un type dbm particulier :

RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"

Ce type peut être choisi parmi sdbm, gdbm, ndbm ou db. Il est cependant recommandé d'utiliser l'utilitaire httxt2dbm fourni avec le serveur HTTP Apache, car il utilise la bibliothèque DBM appropriée, à savoir celle qui a été utilisée lors de la compilation de httpd.

Pour créer un fichier dbm, créez tout d'abord un fichier de correspondances au format texte comme décrit dans la section txt. Traitez ensuite ce fichier avec httxt2dbm :

$ httxt2dbm -i fichier-map.txt -o fichier-map.map

Vous pouvez alors faire référence au fichier obtenu dans votre directive RewriteMap :

RewriteMap mapname "dbm:/etc/apache/mapfile.map"

Notez qu'avec certains types dbm, plusieurs fichiers possédant le même nom de base sont créés. Par exemple, vous pouvez obtenir deux fichiers nommés fichier-map.map.dir et fichier-map.map.pag. Ceci est tout à fait normal, et vous ne devez utiliser que le nom de base fichier-map.map dans votre directive RewriteMap.

Mise en cache des recherches

Les clés de recherche sont mises en cache par httpd jusqu'à ce que le mtime (date de modification) du fichier de correspondances soit modifié, ou que le serveur httpd soit redémarré, ce qui améliore les performances pour les tables de correspondances consultées par de nombreuses requêtes.

prg: Programme de réécriture externe

Lorque le type-map prg est spécifié, la source est un chemin du système de fichiers vers un programme exécutable destiné à effectuer la mise en correspondance. Il peut s'agir d'un fichier binaire compilé, ou d'un programme en langage interprété comme Perl ou Python.

Ce programme est lancé une fois au démarrage du serveur HTTP Apache, puis communique avec le moteur de réécriture via STDIN et STDOUT. En d'autres termes, pour chaque recherche de correspondance, il reçoit un argument via STDIN, et doit renvoyer en guise de réponse une chaîne terminée par un caractère nouvelle-ligne sur STDOUT. Si la recherche de correspondance est infructueuse, le programme doit l'indiquer en retournant la chaîne de quatre caractères "NULL".

Les programmes de réécriture externes ne sont pas lancés s'il n'ont pas été définis dans un contexte où la directive RewriteEngine est définie à on.

Par défaut, les programmes de réécriture externes sont lancés par l'utilisateur root. Pour en changer, il est possible sur les systèmes de style Unix de spécifier un autre couple utilisateur/groupe via le troisième argument de la directive RewriteMap, et ceci au format utilisateur:groupe.

Cette fonctionnalité utilise le mutex rewrite-map nécessaire à la fiabilité des communications avec le programme. Le mécanisme de mutex et le fichier verrou peuvent être définis via la directive Mutex.

Voici un exemple simple qui remplace tous les tirets par des caractères de soulignement dans l'URI de la requête.

Configuration de la réécriture

RewriteMap d2u "prg:/www/bin/dash2under.pl" apache:apache
RewriteRule "-" "${d2u:%{REQUEST_URI}}"

dash2under.pl

    #!/usr/bin/perl
    $| = 1; # Turn off I/O buffering
    while (<STDIN>) {
        s/-/_/g; # Remplace tous les tirets par des caractères de soulignement
        print $_;
    }

Mises en garde !

  • Votre programme doit être le plus simple possible. Si le programme se bloque, httpd va attendre indéfiniment une réponse de sa part, et par conséquent ne répondra plus aux requêtes.
  • Assurez-vous de bien désactiver la mise en tampon dans votre programme. En Perl, ceci est effectué à la seconde ligne du script de l'exemple - $| = 1; - La syntaxe sera bien entendu différente dans d'autres langages. Si les entrées/sorties sont mises en tampon, httpd va attendre une sortie, et va par conséquent se bloquer.
  • Rappelez-vous qu'il n'existe qu'une copie du programme lancé au démarrage du serveur, et que toutes les requêtes vont devoir passer par ce goulot d'étranglement. Ceci peut provoquer des ralentissements significatifs si de nombreuses requêtes doivent être traitées, ou si le script lui-même est très lent.

dbd ou fastdbd: requête SQL

Lorsque le type-map dbd ou fastdbd est spécifié, la source est une requête SQL SELECT qui reçoit un argument et renvoie une seule valeur.

Pour que cette requête puisse être exécutée, mod_dbd doit être configuré pour attaquer la base de données concernée.

Ce type-map existe sous deux formes. Avec le type-map dbd, la requête est exécutée à chaque demande, tandis qu'avec le type-map fastdbd, les recherches dans la base de données sont mises en cache en interne. fastdbd est donc plus efficace et donc plus rapide ; par contre, il ne tiendra pas compte des modifications apportées à la base de données jusqu'à ce que le serveur soit redémarré.

Si une requête renvoie plusieurs enregistrements, un de ceux-ci sera sélectionné aléatoirement.

Exemple

RewriteMap ma-requete "fastdbd:SELECT destination FROM rewrite WHERE source = %s"

Résumé

La directive RewriteMap peut apparaître plusieurs fois. Utilisez une directive RewriteMap pour chaque fonction de mise en correspondance pour déclarer son fichier de correspondances.

Bien que l'on ne puisse pas déclarer de fonction de mise en correspondance dans un contexte de répertoire (fichier .htaccess ou section <Directory>), il est possible d'utiliser cette fonction dans un tel contexte.


Advanced Techniques with mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Advanced Techniques with mod_rewrite

Ce document complète la documentation de référence du module mod_rewrite. Il présente un certain nombre de techniques avancées quant à l'utilisation de mod_rewrite.

Notez que la plupart des exemples ne fonctionneront pas en l'état dans la configuration particulière de votre serveur ; il est donc important de bien comprendre leur fonctionnement, plutôt que de simplement les copier/coller dans votre configuration.

Voir aussi

  • Documentation du module
  • Introduction à mod_rewrite
  • Redirection et remise en correspondance
  • Contrôler l'accès
  • serveurs virtuels
  • serveurs mandataires
  • Utilisation de RewriteMap
  • Quand ne pas utiliser mod_rewrite

Distribution de la charge entre plusieurs serveurs d'arrière-plan en fonction de l'adresse IP

Description :

La fragmentation ou "sharding" est une technique courante de distribution de la charge du serveur ou de l'espace de stockage. Quand on utilise cette méthode, un serveur frontal utilise l'URL pour répartir de manière appropriée les utilisateurs et objets entre différents serveurs d'arrière-plan.

Solution :

On maintient une table de correspondance entre utilisateurs et serveurs cibles dans des fichiers externes. Ces derniers se présentent comme suit :

utilisateur1 serveur_physique_utilisateur1
utilisateur2 serveur_physique_utilisateur2
: :

Tout ceci est enregistré dans un fichier correspondances-utilisateurs-serveurs. Le but est de faire correspondre

/u/utilisateur1/chemin

avec

http://serveur_physique_utilisateur1/u/utilisateur/chemin

il n'est ainsi pas nécessaire que tous les chemins URL soient valides sur tous les serveurs physiques d'arrière-plan. Le jeu de règles suivant fait tout ceci pour nous, en s'appuyant sur les fichiers de correspondances, en supposant que serveur0 est un serveur par défaut qui sera utilisé lorsqu'un utilisateur ne possèdera pas d'entrée dans la table de correspondances :

RewriteEngine on
RewriteMap      users-to-hosts   "txt:/path/to/map.users-to-hosts"
RewriteRule   "^/u/([^/]+)/?(.*)"   "http://${users-to-hosts:$1|server0}/u/$1/$2"

Voir la documentation de RewriteMap pour une description plus approfondie de la syntaxe de cette directive.

Régéneration de contenu à la volée

Description :

Nous voulons générer du contenu de manière dynamique, mais le conserver de manière statique lorsqu'il a été généré. La règle suivante vérifie l'existence du fichier statique, et le génère s'il est absent. Les fichiers statiques peuvent être supprimés périodiquement si on le désire (par exemple via cron), et seront régénérés à la demande.

Solution :
A cet effet, on utilise le jeu de règles suivant :
# Cet exemple n'est valable que dans un contexte de répertoire
RewriteCond "%{REQUEST_URI}"   "!-U"
RewriteRule "^(.+)\.html$"          "/regenerate_page.cgi"   [PT,L]

L'opérateur -U permet de déterminer si la chaîne de test (dans ce cas REQUEST_URI) est une URL valide. Pour ce faire, il utilise une sous-requête. Si cette sous-requête échoue, ou en d'autres termes, si la ressource demandée n'existe pas, cette règle invoque le programme CGI /regenerate_page.cgi qui génère la ressource demandée et la sauvegarde dans le répertoire des documents, de façon à ce qu'une copie statique puisse être servie lors d'une demande ultérieure.

De cette façon, les documents qui ne sont pas mis à jour régulièrement peuvent être servis sous une forme statique. Si ces documents doivent être réactualisés, on peut les supprimer du répertoire des documents, et ils seront ainsi régénérés à la prochaine demande.

Répartition de charge

Description :

Nous voulons répartir la charge de manière aléatoire entre plusieurs serveurs en utilisant mod_rewrite.

Solution :

Pour y parvenir, nous allons utiliser la directive RewriteMap et une liste de serveurs.

RewriteEngine on
RewriteMap lb "rnd:/path/to/serverlist.txt"
RewriteRule "^/(.*)" "http://${lb:serveurs}/$1" [P,L]

liste-serveurs.txt contiendra la liste des serveurs :

## liste-serveurs.txt

serveurs un.example.com|deux.example.com|trois.example.com

Si vous voulez qu'un serveur se voit confier d'avantage de charge que les autres, faites le figurer plusieurs fois dans la liste.

Discussion

Apache possède un module de répartition de charge - mod_proxy_balancer - beaucoup plus souple et présentant plus de fonctionnalités dans ce domaine que mod_rewrite.

Répertoires Home structurés

Description :

Certains sites avec des milliers d'utilisateurs organisent les répertoires utilisateurs de manière structurée, c'est à dire que chaque répertoire utilisateur se trouve dans un sous-répertoire dont le nom commence (par exemple) par le premier caractère du nom de l'utilisateur. Ainsi, /~larry/chemin correspond à /home/l/larry/public_html/chemin, alors que /~waldo/chemin correspond à /home/w/waldo/public_html/chemin.

Solution :

On utilise le jeu de règles suivant pour développer les URLs avec tilde selon l'organisation structurée précédente.

RewriteEngine on
RewriteRule   "^/~(([a-z])[a-z0-9]+)(.*)"  "/home/$2/$1/public_html$3"

Redirection des ancrages

Description :

Par défaut, la redirection vers un ancrage HTML ne fonctionne pas, car mod_rewrite échappe le caractère # en le transformant en %23, ce qui rend la redirection inopérante.

Solution :

On utilise le drapeau [NE] dans la règle RewriteRule. NE signifie "No Escape".

Discussion :
Cette technique fonctionne bien entendu pour tout autre caractère spécial que mod_rewrite, par défaut, code pour insertion dans une URL.

Réécriture dépendant de l'heure

Description :

Nous voulons servir des contenus différents selon l'heure du jour en utilisant mod_rewrite.

Solution :

Il existe de nombreuses variables nommées TIME_xxx utilisables dans les conditions de réécriture. Utilisées en conjonction avec les modèles de comparaison lexicographique spéciaux <STRING, >STRING et =STRING, elles permettent d'effectuer des redirections dépendant de l'heure :

RewriteEngine on
RewriteCond   "%{TIME_HOUR}%{TIME_MIN}" ">0700"
RewriteCond   "%{TIME_HOUR}%{TIME_MIN}" "<1900"
RewriteRule   "^foo\.html$"             "foo.day.html" [L]
RewriteRule   "^foo\.html$"             "foo.night.html"

Avec cet exemple, l'URL foo.html renvoie le contenu de foo.jour.html durant le créneau horaire 07:01-18:59, et le contenu de foo.nuit.html le reste du temps.

mod_cache, les mandataires intermédiaires et les navigateurs peuvent chacun mettre en cache les réponses et ainsi afficher une des deux pages en dehors de la fenêtre de temps configurée. On peut utiliser mod_expires pour contourner ce problème. Il est cependant bien plus commode de servir un contenu dynamique, et de le personnaliser en fonction de l'heure du jour.

Définir des variables d'environnement en fonction de certaines parties de l'URL

Description :

Ici, nous voulons conserver une certaine forme de statut lorsqu'une réécriture a eu lieu. Par exemple, vous souhaitez consigner le fait que cette réécriture a eu lieu, et vous servir plus tard de cette information pour déterminer si une requête sera concernée par cette réécriture. Pour y parvenir, on peut utiliser une variable d'environnement.

Solution :

Utiliser le drapeau [E] pour définir une variable d'environnement.

RewriteEngine on
RewriteRule   "^/cheval/(.*)"   "/poney/$1" [E=rewritten:1]

Plus loin dans votre jeu de règles, vous pouvez vérifier le contenu de cette variable d'environnement via une directive RewriteCond :

RewriteCond "%{ENV:rewritten}" "=1"


Quand ne pas utiliser mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Quand ne pas utiliser mod_rewrite

Ce document est un complément à la Documentation de référence de mod_rewrite. Il décrit peut-être un des concepts les plus importants à propos de mod_rewrite - à savoir, quand doit-on éviter de l'utiliser.

mod_rewrite doit être considéré comme un dernier recours, lorsqu'aucune alternative n'est possible. Utiliser mod_rewrite lorsqu'il existe des alternatives plus simples conduit à des configurations confuses, fragiles, et difficiles à maintenir. La compréhension des autres alternatives disponibles est une étape très importante sur le chemin de la maîtrise de mod_rewrite.

Vous devez vous attacher à comprendre le fonctionnement des exemples, car la plupart d'entre eux ne fonctionneront pas sur votre système si vous vous contentez de les copier/coller dans vos fichiers de configuration.

Le cas le plus courant dans lequel mod_rewrite est l'outil approprié est la situation où la seule solution envisageable nécessite l'accès aux fichiers de configuration du serveur, alors que cet accès ne vous est pas accordé. Certaines directives de configuration ne sont disponibles que dans le fichier de configuration du serveur. Si vous ne pouvez agir que sur les fichiers .htaccess, vous devrez donc vous tourner vers mod_rewrite.

Voir aussi

  • Documentation du module mod_rewrite
  • Introduction à mod_rewrite
  • Redirection et remise en correspondance
  • Contrôle d'accès
  • Serveurs virtuels
  • Serveurs mandataires
  • Utilisation de RewriteMap
  • Techniques avancées

Redirection simple

mod_alias fournit les directives Redirect et RedirectMatch qui permettent de rediriger une URL vers une autre. Plutôt que d'utiliser la directive RewriteRule pour ce genre de redirection simple d'une URL ou d'une classe d'URLs vers une autre, on préfèrera l'utilisation de ces directives. En outre, avec RedirectMatch, vous pouvez inclure une expression rationnelle dans votre critère de redirection, ce qui vous permet de bénéficier de nombreux avantages de la directive RewriteRule.

Une utilisation courante de la directive RewriteRule est la redirection de toute une classe d'URLs. Par exemple, toutes les URLs faisant référence au répertoire /un doivent être redirigées vers http://un.example.com/, ou toutes les requêtes http doivent être redirigées vers https.

Pour ce faire, il est préférable d'utiliser la directive Redirect. Souvenez-vous que la directive Redirect conserve les informations relatives au chemin. En d'autres termes, la redirection d'une URL /un va aussi rediriger toutes les URLs de niveaux inférieurs comme /un/deux.html et /un/trois/quatre.html.

Pour rediriger les URLs sous /un vers http://un.example.com/, utilisez cette définition :

Redirect /one/ http://one.example.com/

Pour rediriger un nom d'hôte vers un autre nom d'hôte, par exemple example.com vers www.example.com, voir la méthode Noms d'hôtes canoniques.

Pour rediriger les URLs http vers https, utilisez cette définition :

<VirtualHost *:80>
ServerName www.example.com
Redirect "/" "https://www.example.com/"
</VirtualHost>

<VirtualHost *:443>
ServerName www.example.com
#  ... insérer ici la configuration SSL
</VirtualHost>

L'utilisation de la directive RewriteRule pour accomplir cette tâche peut se justifier s'il existe d'autres directives RewriteRule dans la même portée. En effet, lorsque des directives Redirect et RewriteRule se trouvent dans la même portée, les directives RewriteRule sont exécutées en premier, sans tenir compte de leur ordre d'apparition dans le fichier de configuration.

Dans le cas de la redirection http-vers-https, l'utilisation de règles RewriteRule se justifie si vous n'avez pas accès au fichier de configuration principal, et devez donc accomplir cette tâche au sein d'un fichier .htaccess.

Alias d'URL

La directive Alias permet de mettre en correspondance un URI avec un répertoire, ce dernier étant en général situé en dehors de l'arborescence définie par la directive DocumentRoot. Bien qu'il soit possible d'effectuer cette mise en correspondance avec mod_rewrite, il est préférable d'utiliser la directive Alias pour des raisons de simplicité et de performances.

Utilisation de la directive Alias

Alias "/cats" "/var/www/virtualhosts/felines/htdocs"

Pour effectuer cette mise en correspondance, mod_rewrite s'impose si vous n'avez pas accès aux fichiers de configuration du serveur. En effet, la directive Alias ne peut pas être utilisée dans un fichier .htaccess, mais seulement dans un contexte de serveur principal ou de serveur virtuel.

En outre, vous pouvez arriver au même résultat avec les liens symboliques, pourvu que Options FollowSymLinks soit activé sur votre serveur.

Hébergement virtuel

Bien qu'il soit possible de gérer les serveurs virtuels avec mod_rewrite, il s'agit rarement de la bonne méthode. Il est pratiquement toujours préférable de créer des blocs <VirtualHost> individuels. Dans l'éventualité où vous devez gérer un grand nombre de serveurs virtuels, vous devez vous tourner vers mod_vhost_alias pour créer ces serveurs automatiquement.

Il est aussi possible d'utiliser des modules comme mod_macro pour créer un grand nombre de serveurs virtuels dynamiquement.

L'utilisation de mod_rewrite pour la création de serveurs virtuels peut se révéler appropriée si votre service d'hébergement ne vous permet pas d'accéder aux fichiers de configuration du serveur, et que vous soyez par conséquent obligé de passer par les fichiers .htaccess.

Voir le document création de serveurs virtuels avec mod_rewrite pour plus de détails sur la manière d'y parvenir si cela semble être tout de même la meilleure approche.

Mandat simple

La directive RewriteRule fournit le drapeau [P] qui permet de faire passer les URIs réécrits par mod_proxy.

RewriteRule "^/?images(.*)" "http://serveur-images.local/images$1" [P]

Cependant, dans les nombreux cas où aucune correspondance au modèle n'est vraiment nécessaire, comme dans l'exemple ci-dessus, il est préférable d'utiliser la directive ProxyPass. L'exemple précédent pourrait être remplacé par :

ProxyPass "/images/" "http://serveur-images.local/images/"

Que vous utilisiez RewriteRule ou ProxyPass, vous devrez dans tous les cas utiliser aussi la directive ProxyPassReverse pour intercepter les redirections en provenance du serveur d'arrière-plan :

ProxyPassReverse "/images/" "http://serveur-images.local/images/"

Vous devrez cependant tout de même utiliser RewriteRule lorsque d'autres RewriteRules se trouvent dans la même portée, car elles agissent en général avant les directives ProxyPass, et peuvent ainsi les court-circuiter.

Test de variables d'environnement

mod_rewrite est souvent utilisé pour effectuer une action en fonction de la présence ou de l'absence d'une variable d'environnement particulière ou d'un en-tête de requête, ce qui peut être accompli de manière plus efficace via la directive <If>.

Considérons par exemple le scénario courant où la directive RewriteRule est utilisée pour forcer un nom d'hôte canonique, tel que www.example.com au lieu de example.com. Il est possible d'utiliser à la place la directive <If> comme suit :

<If "req('Host') != 'www.example.com'">
    Redirect "/" "http://www.example.com"
</If>

On peut utiliser cette technique dans de nombreux scénarios courant pour remplacer mod_rewrite pour effectuer des actions en fonction d'en-têtes de requêtes ou de réponses, ou de variables d'environnement.

Voir en particulier la documentation sur l'évaluation des expressions pour une vue d'ensemble des types d'expressions que vous pouvez utiliser dans les sections <If>, ainsi que dans certaines directives.


Les drapeaux de réécriture - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Les drapeaux de réécriture

Ce document décrit les drapeaux disponibles dans la directive RewriteRule, en fournissant des explications détaillées et des exemples.

Voir aussi

  • Documentation du module
  • Introduction à mod_rewrite
  • Redirection and remise en correspondance
  • Contrôle d'accès
  • Serveurs virtuels
  • Mise en cache
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

Introduction

Le comportement d'une directive RewriteRule peut être modifié par un ou plusieurs drapeaux. Les drapeaux sont situés en fin de règle, entourés de crochets, et séparés le cas échéant par des virgules.

RewriteRule pattern target [Flag1,Flag2,Flag3]

Chaque drapeau (à quelques exceptions près) possède une forme courte, comme CO, ainsi qu'une forme longue, comme cookie. Bien que la forme courte soit la plus couramment utilisée, nous vous recommandons de vous familiariser avec les drapeaux sous leur forme longue, afin de bien mémoriser ce que chaque drapeau est supposé faire. Certains drapeaux acceptent un ou plusieurs arguments. Les drapeaux ne sont pas sensibles à la casse.

Les drapeaux qui modifient les métadonnées associées à la requête (T=, H=, E=) n'ont aucun effet dans un contexte de répertoire ou de fichier htaccess, lorsqu'une substitution (autre que '-') est effectuée au cours de la même passe du processus de réécriture.

Chaque drapeau disponible est présenté ici, avec un exemple d'utilisation.

B (échappement dans les références arrières)

Avec le drapeau [B], la directive RewriteRule échappe les caractères non-alphanumériques avant d'appliquer la transformation. A partir de la version 2.4.26, vous pouvez limiter l'échappement dans les références arrières à une liste de caractères que vous pouvez spécifiez comme dans cet exemple : [B=#?;]. Notez que l'espace peut faire partie de la liste des caractères à échapper, mais qu'il ne doit pas être le dernier caractère de cette liste.

mod_rewrite doit supprimer les séquences d'échappement des URLs avant leur mise en correspondance avec le système de fichiers ; les séquences d'échappement sont donc supprimées des références arrières au moment où ces dernières sont appliquées. Avec le drapeau B, les caractères non-alphanumériques des références arrières seront échappés. Considérons par exemple cette règle :

RewriteRule "^search/(.*)$" "/search.php?term=$1"

Soit le terme de recherche 'x & y/z' ; un navigateur va le coder en 'x%20%26%20y%2Fz', transformant la requête en 'search/x%20%26%20y%2Fz'. Sans le drapeau B, cette règle de réécriture va réécrire la requête en 'search.php?term=x & y/z', ce qui ne correspond pas à une URL valide et cette dernière sera encodée en search.php?term=x%20&y%2Fz=, ce qui ne correspond pas à ce que l'on souhaitait.

Avec le drapeau B, les paramètres sont réencodés avant d'être passés à l'URL résultante, ce qui fournit une réécriture correcte en /search.php?term=x%20%26%20y%2Fz.

RewriteRule "^search/(.*)$" "/search.php?term=$1" [B,PT]

Notez que vous devrez peut-être aussi définir la directive AllowEncodedSlashes à On pour que cet exemple particulier fonctionne, car httpd ne permet pas les slashes encodés dans les URLs, et renvoie une erreur 404 s'il en rencontre un.

Ce processus d'échappement est en particulier nécessaire dans le contexte d'un mandataire, où l'accès au serveur d'arrière-plan échouera si on présente à ce dernier une URL non échappée.

Une alternative à ce drapeau consiste à utiliser une directive RewriteCond pour capturer %{THE_REQUEST}, les chaînes capturées se présentant alors sous la forme codée.

BNP|backrefnoplus (ne pas échapper l'espace en +)

Si le drapeau [BNP] est spécifié, la directive RewriteRule échappera le caractère espace en %20 au lieu de '+' dans les références arrières. Ceci s'avère utile lorsque la référence arrière est utilisée dans la partie chemin, et non dans les paramètres de la requête.

Ce drapeau est disponible à partir de la version 2.4.26 du serveur HTTP Apache.

C|chain

Le drapeau [C] ou [chain] indique que la règle RewriteRule est chaînée avec la suivante. Autrement dit, si la règle s'applique, elle est traitée normalement et passe le contrôle à la règle suivante. Par contre, si elle ne s'applique pas, la règle suivante, ainsi que toutes les règles chaînées qui suivent, seront sautées.

CO|cookie

Le drapeau [CO], ou [cookie], vous permet de définir un cookie lorsqu'une règle RewriteRule s'applique. Il possède trois arguments obligatoires et quatre arguments optionnels.

La syntaxe complète de ce drapeau, avec tous ses attributs, est la suivante :

[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]

Si un caractère littéral ':' doit être insérer dans un des champs du cookie, une autre syntaxe est disponible. Pour utiliser cette syntaxe alternative, le contenu du champ "Name" doit être précédé du caractère ';', et les sépateurs de champs deviendront des ';'.

[CO=;NAME;VALUE:MOREVALUE;DOMAIN;lifetime;path;secure;httponly]

Vous devez déclarer un nom, une valeur et un domaine pour que le cookie puisse être défini.

Domain
Le domaine pour lequel vous souhaitez que le cookie soit valide. Ce peut être un nom de serveur, comme www.example.com, ou un domaine, comme .example.com. Il doit comporter au moins deux parties séparées par un point. C'est à dire que vous ne pouvez pas utiliser les valeurs .com ou .net. En effet, ce style de cookie est interdit par le modèle de sécurité des cookies.

Vous pouvez aussi définir les valeurs suivantes :

Lifetime
La durée de vie du cookie, en minutes.
Une valeur de 0 indique une durée de vie correspondant à la session courante du navigateur. Il s'agit de la valeur par défaut.
Path
Le chemin, sur le site web concerné, pour lequel le cookie est valide, du style /clients/ or /fichiers/telechargement/.
La valeur par défaut est / - c'est à dire l'ensemble du site web.
Secure
Si cet argument a pour valeur secure, true, ou 1, le cookie ne pourra être transmis que dans le cadre d'une connexion sécurisée (https).
httponly
Si cet argument a pour valeur HttpOnly, true, ou 1, le cookie aura son drapeau HttpOnly activé, ce qui signifie qu'il sera inaccessible au code JavaScript pour les navigateurs qui supportent cette fonctionnalité.

Voici un exemple :

RewriteEngine On
RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.org:1440:/]

Dans l'exemple ci-dessus, la règle ne réécrit pas la requête. La cible de réécriture "-" indique à mod_rewrite de transmettre la requête sans modification. Par contre, il définit un cookie nommé 'frontdoor' avec une valeur 'yes'. Le cookie est valide pour tout hôte situé dans le domaine .example.org. Sa durée de vie est limitée à 1440 minutes (24 heures), et il sera renvoyé pour tous les URIs.

DPI|discardpath

Avec le drapeau DPI, la partie PATH_INFO de l'URI réécrit est supprimée.

Ce drapeau est disponible dans les versions 2.2.12 et supérieures.

Dans un contexte de répertoire, l'URI mis en comparaison par chaque règle RewriteRule est la concaténation des valeurs courantes de l'URI et de PATH_INFO.

L'URI courant peut être l'URI initial tel qu'il a été fourni par le client, le résultat d'une passe précédente du processus de réécriture, ou le résultat de la règle précédente dans le processus courant de réécriture.

Par contre, la partie PATH_INFO ajoutée à l'URI avant chaque règle ne reflète que la valeur de PATH_INFO avant la passe courante du processus de réécriture. En conséquence, si de larges portions de l'URI correspondent et sont traduites via plusieurs directives RewriteRule, sans prendre en compte quelles parties de l'URI provenaient du PATH_INFO courant, l'URI final pourra se voir ajouter plusieurs copies de PATH_INFO.

Utilisez ce drapeau pour toute substitution où la présence du PATH_INFO qui résultait de la mise en correspondance précédente de cette requête avec le système de fichier n'est pas nécessaire. Avec ce drapeau, le PATH_INFO établi avant que cette passe du processus de réécriture ne débute est oublié. PATH_INFO ne sera pas recalculé tant que la passe courante du processus de réécriture ne sera pas achevée. Les règles suivantes de cette passe ne verront que le résultat direct des substitutions, sans aucun PATH_INFO ajouté.

E|env

Avec le drapeau [E], ou [env], vous pouvez définir la valeur d'une variable d'environnement. Notez que certaines variables d'environnement peuvent être définies après le traitement de la règle, annulant par la-même ce que vous avez défini. Voir le document sur les variables d'environnement pour plus de détails sur le fonctionnement des variables d'environnement.

La syntaxe complète pour ce drapeau est :

[E=!VAR]

VAL peut comporter des références arrières ($N ou %N) qui seront développées.

En utilisant la version courte

[E=VAR]

vous pouvez définir la variable d'environnement nommée VAR avec une valeur vide.

La forme

[E=!VAR]

permet d'annuler la définition de la variable VAR.

Les variables d'environnement s'emploient dans différents contextes, comme les programmes CGI, d'autres directives RewriteRule, ou des directives CustomLog.

L'exemple suivant définit une variable d'environnement nommée 'image' avec une valeur de '1' si l'URI de la requête correspond à un fichier image. Cette variable d'environnement est ensuite utilisée pour exclure une telle requête du journal des accès.

RewriteRule "\.(png|gif|jpg)" "-" [E=image:1]
CustomLog "logs/access_log" combined env=!image

Notez que le même effet peut être obtenu à l'aide de la directive SetEnvIf. Cette technique est présentée à titre d'exemple et non de recommandation.

END

L'utilisation du drapeau [END] permet non seulement de terminer le processus de réécriture en cours (comme [L]), mais aussi d'empêcher tout processus de réécriture ultérieur dans un contexte de répertoire (htaccess).

Ceci ne s'applique pas aux nouvelles requêtes résultant d'une redirection externe.

F|forbidden

L'utilisation du drapeau [F] permet de faire envoyer par le serveur au client un code de statut "403 Forbidden". Le même effet peut être obtenu à l'aide de la directive Deny, mais ce drapeau offre plus de souplesse dans l'attribution d'un statut Forbidden.

La règle suivante va interdire la téléchargement de fichiers .exe depuis votre serveur.

RewriteRule "\.exe" "-" [F]

Cet exemple utilise la syntaxe "-" pour la cible de réécriture, ce qui signifie que l'URI de la requête n'est pas modifié. Il n'y a aucune raison de réécrire un URI, si vous avez l'intention d'interdire la requête.

Lorsqu'on utilise [F], [L] est implicite - c'est à dire que la réponse est renvoyée immédiatement, et aucune autre règle n'est évaluée.

G|gone

Le drapeau [G] permet de faire envoyer par le serveur un code de statut "410 Gone" avec la réponse. Ce code indique qu'une ressource qui était disponible auparavant ne l'est plus actuellement.

Comme dans le cas du drapeau [F], on utilise en général la syntaxe "-" pour la cible de réécriture lorsqu'on utilise le drapeau [G] :

RewriteRule "oldproduct" "-" [G,NC]

Lorsqu'on utilise [G], [L] est implicite - c'est à dire que la réponse est renvoyée immédiatement, et aucune autre règle n'est évaluée.

H|handler

Force le traitement de la requête résultante par le gestionnaire spécifié. Par exemple, on peut utiliser ce drapeau pour forcer l'interprétation de tous les fichiers sans extension par le gestionnaire php :

RewriteRule "!\." "-" [H=application/x-httpd-php]

L'expression rationnelle ci-dessus - !\. - correspond à toute requête qui ne contient pas le caractère ..

On peut aussi utiliser ce drapeau pour forcer l'utilisation d'un certain gestionnaire en fonction de certaines conditions. Par exemple, l'extrait suivant utilisé dans un contexte de niveau serveur permet de faire en sorte que les fichiers .php soient affichés par mod_php dans le cas où ils font l'objet d'une requête avec l'extension .phps :

RewriteRule "^(/source/.+\.php)s$" "$1" [H=application/x-httpd-php-source]

L'expression rationnelle ci-dessus - ^(/source/.+\.php)s$ - va correspondre à toute requête qui débutera par /source/, continuera par 1 ou n caractères puis par .phps. La référence arrière $1 fait référence à la correspondance capturée entre parenthèses de l'expression rationnelle.

L|last

Lorsque le drapeau [L] est présent, mod_rewrite arrête le traitement du jeu de règles. Cela signifie dans la plupart des situations que si la règle s'applique, aucune autre règle ne sera traitée. Ce drapeau correspond à la commande Perl last, ou à la commande break en C. Utilisez ce drapeau pour indiquer que la règle courante doit être appliquée immédiatement, sans tenir compte des règles ultérieures.

Si vous utilisez des règles RewriteRule dans des fichiers .htaccess ou des sections <Directory>, il est important d'avoir quelques notions sur la manière dont les règles sont traitées. Pour simplifier, une fois les règles traitées, la requête réécrite est passée à nouveau au moteur d'interprétation des URLs afin que ce dernier puisse la traiter. Il est possible qu'au cours du traitement de la requête réécrite, le fichier .htaccess ou la section <Directory> soient à nouveau rencontrés, entraînant un nouveau traitement du jeu de règles depuis le début. Cette situation se présente le plus souvent lorsqu'une des règles provoque une redirection - interne ou externe - ce qui réinitialise le traitement de la requête.

Si vous utilisez des directives RewriteRule dans un de ces contextes, il importe par conséquent de prévoir explicitement des étapes permettant d'éviter un bouclage infini sur les règles, et de ne pas compter seulement sur le drapeau [L] pour terminer l'exécution d'une série de règles, comme décrit ci-dessous.

Un autre drapeau, [END], permet non seulement d'interrompre le cycle courant du processus de réécriture, mais aussi d'empêcher toute réécriture ultérieure dans le contexte de répertoire (htaccess). Ceci ne s'applique pas aux nouvelles requêtes résultant de redirections externes.

Dans l'exemple donné ici, toute requête est réécrite en index.php, la requête originale étant ajoutée comme chaîne de requête en argument à index.php ; cependant, la directive RewriteCond permet de s'assurer que si la requête concerne déjà index.php, la directive RewriteRule sera sautée.

RewriteBase "/"
RewriteCond "%{REQUEST_URI}" "!=/index.php"
RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]

N|next

Le drapeau [N] provoque un redémarrage du traitement des règles depuis le début, en utilisant le résultat du jeu de règles, sous réserve qu'il existe un point de démarrage ; à utiliser avec précautions car il peut provoquer un bouclage infini.

Le drapeau [Next] peut servir, par exemple, à remplacer de manière répétitive une chaîne de caractère ou une lettre dans une requête. Dans l'exemple suivant, chaque occurence de A sera remplacée par B dans la requête, et ceci jusqu'il n'y ait plus de A à remplacer.

RewriteRule "(.*)A(.*)" "$1B$2" [N]

Vous pouvez vous représenter ce traitement comme une boucle while : tant que le modèle de la règle correspond (c'est à dire, tant que l'URI contient un A), effectuer la substitution (c'est à dire, remplacer le A par un B).

A partir de la version 2.4.8, ce module renvoie une erreur après 32000 itérations afin d'éviter les boucles infinies. Ce nombre maximum d'itération peut être modifié via le drapeau N.

# On veut remplacer 1 caractère à chaque itération de la boucle
RewriteRule "(.+)[><;]$" "$1" [N=64000]
# ... ou s'arrêter après 10 itérations
RewriteRule "(.+)[><;]$" "$1" [N=10]

NC|nocase

Avec le drapeau [NC], le modèle de la règle RewriteRule est comparé à la requête de manière insensible à la casse. C'est à dire que cette comparaison s'effectue sans tenir compte des majuscules/minuscules dans l'URI comparé.

Dans l'exemple suivant, toute requête pour un fichier image sera transmise par Apache à votre serveur d'images dédié. La correspondance est insensible à la casse, si bien que par exemple, .jpg aussi bien que .JPG seront acceptés.

RewriteRule "(.*\.(jpg|gif|png))$" "http://images.example.com$1" [P,NC]

NE|noescape

Par défaut, les caractères spéciaux, comme & et ?, sont convertis en leur équivalent hexadécimal. Le drapeau [NE] permet d'éviter cette conversion.

RewriteRule "^/anchor/(.+)" "/bigpage.html#$1" [NE,R]

Dans l'exemple ci-dessus, /anchor/xyz est réécrit en /bigpage.html#xyz. En l'absence du drapeau [NE], le # aurait été converti en son équivalent hexadécimal, %23, ce qui aurait provoqué un code d'erreur "404 Not Found".

NS|nosubreq

Le drapeau [NS] empêche la règle de s'appliquer aux sous-requêtes. Par exemple, une page incluse au moyen d'une SSI (Server Side Include) est une sous-requête, et vous ne voudrez probablement pas que la réécriture s'applique à ces sous-requêtes. Ainsi, lorsque mod_dir recherche des informations à propos des fichiers par défaut du répertoire (comme les fichiers index.html), il s'agit d'une sous-requête interne, et vous ne désirez en général pas que ces sous-requêtes soient réécrites. Cette réécriture n'est pas toujours utile pour les sous-requêtes, et peut même causer des erreurs si l'ensemble du jeu de règles est appliqué. L'utilisation de ce drapeau permet d'exclure les règles qui peuvent poser problème.

Comment déterminer si vous devez utiliser cette règle ou non : si vous préfixez les URLs avec des scripts CGI, afin de forcer leur traitement par le script CGI, vous vous exposez à des problèmes (ou du moins à une surcharge significative) avec les sous-requêtes. Dans ces cas, vous devez utiliser ce drapeau.

Les images, scripts java, ou fichiers css, chargés en tant que partie d'une page html, ne sont pas des sous-requêtes - le navigateur les appelle sous forme de requêtes HTTP à part entière.

P|proxy

L'utilisation du drapeau [P] entraîne le traitement de la requête par le module mod_proxy, et ceci via une requête de mandataire. Par exemple, si vous voulez que toutes les requêtes d'images soient traitées par un serveur d'images annexe, vous pouvez utiliser une règle de ce style :

RewriteRule "/(.*)\.(jpg|gif|png)$" "http://images.example.com/$1.$2" [P]

L'utilisation du drapeau [P] provoque aussi l'effet du drapeau [L] - autrement dit, la requête est immédiatement envoyée au mandataire, et toute règle ultérieure sera ignorée.

Vous devez vous assurer que la chaîne de substitution soit un URI valide (commençant typiquement par http://nom-serveur) qui puisse être traitée par le module mod_proxy. Dans le cas contraire, le module mandataire vous renverra une erreur. L'utilisation de ce drapeau implémente de manière plus puissante la directive ProxyPass, pour faire correspondre le contenu distant à l'espace de nommage du serveur local.

Avertissement à propos de la sécurité

Lors de la construction de l'URL cible de la règle, il convient de prendre en compte l'impact en matière de sécurité qu'aura le fait de permettre au client d'influencer le jeu d'URLs pour lesquelles votre serveur agira en tant que mandataire. Assurez-vous que la partie protocole://nom-serveur de l'URL soit fixe, ou ne permette pas au client de l'influencer induement.

Avertissement au sujet des performances

Utiliser ce drapeau fait intervenir mod_proxy sans la gestion des connexions persistantes, ce qui signifie que vous obtiendrez des performances meilleurs si vous utilisez ProxyPass ou ProxyPassMatch.

Ceci est du au fait que ce drapeau induit l'utilisation du worker par défaut, qui ne gère pas la mise en commun et la réutilisation des connexions.

Partout où cela est possible, préférez l'utilisation de ces directives.

Note: mod_proxy doit être activé pour pouvoir utiliser ce drapeau.

PT|passthrough

Par défaut, la cible (ou chaîne de substitution) d'une règle RewriteRule est sensée être un chemin de fichier. Avec le drapeau [PT], par contre, elle est traitée comme un URI. Autrement dit, avec le drapeau [PT], le résultat de la règle RewriteRule est passé à nouveau au système de mise en correspondance des URLs avec le système de fichiers, de façon à ce que les systèmes de mise en correspondance basés sur les chemins de fichiers, comme la directive Alias, Redirect, ou ScriptAlias, par exemple, puissent avoir une chance d'accomplir leur tâche.

Si par exemple, vous avez un Alias pour /icons, et une règle RewriteRule qui renvoie vers /icons, vous devez utiliser le drapeau [PT] pour être sûr que l'Alias sera bien évalué.

Alias "/icons" "/usr/local/apache/icons"
RewriteRule "/pics/(.+)\.jpg$" "/icons/$1.gif" [PT]

Dans l'exemple précédent, en l'absence du drapeau [PT], l'Alias aurait été ignoré, ce qui aurait provoqué une erreur 'File not found'.

Avec le drapeau PT, le drapeau L est implicite : la réécriture s'arrêtera afin de transmettre la requête à la phase suivante du traitement.

Notez que le drapeau PT est implicite dans des contextes de répertoire comme les sections <Directory> ou les fichiers .htaccess. Le seul moyen de contourner ceci consiste à réécrire vers -.

QSA|qsappend

Quand l'URI de remplacement contient une chaîne de requête, le comportement par défaut de la règle RewriteRule est de supprimer la query string (il s'agit des paramètres éventuellement passés dans l'URL après le caractère ?, usuellement pour les formulaires traités par la méthode HTTP GET) existante, et de la remplacer par celle nouvellement créée. Avec le drapeau [QSA], les chaînes de requête peuvent être combinées.

Considérons la règle suivante :

RewriteRule "/pages/(.+)" "/page.php?page=$1" [QSA]

Avec le drapeau [QSA], une requête pour /pages/123?one=two sera réécrite en /page.php?page=123&one=two. Sans le drapeau [QSA], la même requête sera réécrite en /page.php?page=123 - autrement dit, la chaîne de requête (query string) existante sera supprimée.

QSD|qsdiscard

Lorsque l'URI de la requête contient une chaîne de paramètres, et si l'URI cible n'en contient pas, le comportement par défaut de la directive RewriteRule consiste à copier cette chaîne de paramètres dans l'URI cible. Avec le drapeau [QSD], la chaîne de paramètres est supprimée.

Ce drapeau est disponible dans les versions 2.4.0 et supérieures.

Lorsque les drapeaux [QSD] et [QSA] sont utilisés ensemble, c'est le drapeau [QSD] qui l'emporte.

Si l'URI cible possède une chaîne de paramètres, le comportement par défaut sera respecté - c'est à dire que la chaîne de paramètres originale sera supprimée et remplacée par la chaîne de paramètres de l'URI cible.

QSL|qslast

Par défaut, le premier (le plus à gauche) point d'interrogation de la substitution sépare le chemin de la requête de sa chaîne de paramètres. Avec le drapeau [QSL] au contraire, les deux composants seront séparés en utilisant le dernier (le plus à droite) point d'interrogation.

Cela peut s'avérer utile lorsqu'on recherche un fichier dont le nom contient des points d'interrogation. Si aucune chaîne de paramètre n'est présente dans la substitution, il est alors possible d'ajouter un point d'interrogation à la fin et d'utiliser ce drapeau.

Ce drapeau est disponible à partir de la version 2.4.19 du serveur HTTP Apache.

R|redirect

L'utilisation du drapeau [R] provoque l'envoi d'une redirection au navigateur. Si une URL pleinement qualifiée (FQDN - fully qualified domain name) est spécifiée (c'est à dire incluant http://nom-du-serveur/), une redirection sera effectuée vers cette adresse. Dans le cas contraire, le protocole courant, le nom du serveur et le numéro de port seront utilisés pour générer l'URL envoyée avec la redirection.

Tout code de statut de réponse HTTP valide peut être spécifié, en utilisant la syntaxe [R=305], le code de statut 302 étant utilisé par défaut si aucun code n'est spécifié. Le code de statut spécifié n'est pas nécessairement un code de statut de redirection (3xx). Cependant, si le code de statut est en dehors de la plage des codes de redirection (300-399), la chaîne de substitution est entièrement supprimée, et la réécriture s'arrête comme si le drapeau L était utilisé.

En plus des codes de statut de réponse, vous pouvez spécifier les codes de redirection en utilisant leurs noms symboliques : temp (défaut), permanent, ou seeother.

Vous utiliserez presque toujours [R] en conjonction avec [L] (c'est à dire [R,L]), car employé seul, le drapeau [R] préfixe l'URI avec http://cet-hôte[:ce-port], mais passe ensuite cette adresse à la règle suivante, ce qui provoquera le plus souvent des avertissements 'Invalid URI in request'.

S|skip

Le drapeau [S] sert à sauter des règles que vous ne voulez pas voir exécuter. La syntaxe du drapeau [S] est [S=N], où N correspond au nombre de règles à sauter (sous réserve que la règle RewriteRule corresponde). Ceci peut s'interpréter comme une instruction goto dans votre jeu de règles de réécriture. Dans l'exemple suivant, nous ne voulons exécuter la règle RewriteRule que si l'URI demandé ne correspond pas à un fichier existant.

# La requête concerne-t-elle un fichier qui n'existe pas ?
RewriteCond "%{REQUEST_FILENAME}" "!-f"
RewriteCond "%{REQUEST_FILENAME}" "!-d"
# Si c'est la cas, on saute les deux règles de réécriture suivantes
RewriteRule ".?" "-" [S=2]

RewriteRule "(.*\.gif)" "images.php?$1"
RewriteRule "(.*\.html)" "docs.php?$1"

Cette technique trouve son utilité dans le fait qu'une directive RewriteCond ne s'applique qu'à la règle qui la suit immédiatement. Ainsi, si vous voulez qu'une directive RewriteCond s'applique à plusieurs règles RewriteRule, une technique possible consiste à inverser ces conditions et ajouter une RewriteRule avec le drapeau [Skip]. Cette technique permet d'élaborer des pseudo-constructions if-then-else : la dernière règle du bloc then contiendra skip=N, où N est le nombre de règles contenues dans le bloc else :

# Est-ce que le fichier existe ?
RewriteCond "%{REQUEST_FILENAME}" "!-f"
RewriteCond "%{REQUEST_FILENAME}" "!-d"
# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
RewriteRule ".?" "-" [S=3]

# Si le fichier existe, alors :
RewriteRule "(.*\.gif)" "images.php?$1"
    RewriteRule "(.*\.html)" "docs.php?$1"
    # Skip past the "else" stanza.
    RewriteRule ".?" "-" [S=1]
# ELSE...
RewriteRule "(.*)" "404.php?file=$1
# END

Il est probablement plus aisé de définir ce genre de configuration via les directives <If>, <ElseIf>, et <Else>.

T|type

Définit le type MIME de la réponse résultante renvoyée. L'effet est identique à celui de la directive AddType.

Par exemple, vous pouvez utiliser la technique suivante pour servir du code source Perl en tant que plein texte, s'il est requis d'une certaine manière :

# Sert les fichier .pl en tant que plein texte
RewriteRule "\.pl$" "-" [T=text/plain]

Ou encore, si vous possédez une caméra qui produit des fichiers images jpeg sans extension, vous pouvez forcer le renvoi de ces images avec le type MIME correct en se basant sur le nom du fichier :

# Les fichiers dont le nom contient 'IMG' sont des images jpg.
RewriteRule "IMG" "-" [T=image/jpg]

Notez cependant qu'il s'agit d'un exemple trivial, et que le problème aurait pu être résolu en utilisant à la place la directive <FilesMatch>. Il faut toujours envisager la possibilité d'une solution alternative à un problème avant d'avoir recours à la réécriture, qui sera toujours moins efficace qu'une solution alternative.

Dans un contexte de niveau répertoire, n'utilisez que - (tiret) comme substitution, dans toute la séquence de réécriture de mod_rewrite, sinon le type MIME défini avec ce drapeau sera perdu suite à un retraitement interne (y compris les séquences de réécriture suivantes de mod_rewrite). Dans ce contexte, vous pouvez utiliser le drapeau L pour terminer la séquence courante de réécriture de mod_rewrite.


Détails techniques sur le module Apache mod_rewrite - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Rewrite

Détails techniques sur le module Apache mod_rewrite

Ce document passe en revue certains détails techniques à propos du module mod_rewrite et de la mise en correspondance des URLs

Voir aussi

  • Documentation du module mod_rewrite
  • Introduction à mod_rewrite
  • Redirection et remise en correspondance
  • Contrôle d'accès
  • Serveurs virtuels
  • Mise en cache
  • Utilisation de RewriteMap
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite

Phases de l'API

Le traitement des requêtes par le serveur HTTP Apache se déroule en plusieurs phases. Au cours de chaque phase, un ou plusieurs modules peuvent être appelés pour traiter la partie concernée du cycle de vie de la requête. Les différentes phases peuvent consister en traduction d'URL en nom de fichier, authentification, autorisation, gestion de contenu ou journalisation (la liste n'est pas exhaustive).

mod_rewrite agit dans deux de ces phases (ou accroches - hooks - comme on les nomme souvent) pour la réécriture des URLs.

Tout d'abord, il utilise le hook traduction URL vers nom de fichier qui intervient après la lecture de la requête HTTP, mais avant le processus d'autorisation. Ensuite, il utilise le hook Fixup, qui intervient après les phases d'autorisation, après la lecture des fichiers de configuration de niveau répertoire (fichiers .htaccess), mais avant l'appel du gestionnaire de contenu.

Ainsi, lorsqu'une requête arrive et une fois le serveur correspondant ou le serveur virtuel déterminé, le moteur de réécriture commence à traiter toute directive apparaissant dans la configuration de niveau serveur (autrement dit dans le fichier de configuration principal du serveur et les sections <Virtualhost>). Tout ce processus s'exécute au cours de la phase de traduction URL vers nom de fichier.

Quelques étapes plus loin, une fois les répertoires de données finaux trouvés, les directives de configuration de niveau répertoire (fichiers .htaccess et sections <Directory>) sont appliquées. Ce processus s'exécute au cours de la phase Fixup.

Dans tous ces cas, mod_rewrite réécrit le REQUEST_URI soit vers une nouvelle URL, soit vers un nom de fichier.

Dans un contexte de niveau répertoire (autrement dit dans les fichiers .htaccess et les sections Directory), les règles de réécriture s'appliquent après la traduction de l'URL en nom de fichier. C'est pourquoi le chemin URL auquel mod_rewrite compare initialement les directives RewriteRule est le chemin complet vers le nom de fichier traduit amputé de la partie répertoires (y compris le dernier slash).

Un exemple : si les règles se trouvent dans /var/www/foo/.htaccess et si une requête pour /foo/bar/baz est traité, une expression comme ^bar/baz$ correspondra.

Si une substitution intervient dans un contexte de répertoire, une nouvelle sous-requête interne est générée avec la nouvelle URL, ce qui relance le traitement des phases de la requête. Si la substitution est un chemin relatif, la directive RewriteBase détermine le chemin URL devant préfixer cette substitution. Dans un contexte de répertoire, il faut s'assurer de créer des règles qui n'effectueront pas de substitution au cours d'une passe ultérieure du processus de réécriture au niveau répertoire afin d'éviter les bouclages . Voir Bouclage dans le processus de réécriture pour une discussion plus détaillée à propos de ce problème.

En conséquence de cette manipulation de l'URL , vous devrez pensez à confectionner différemment vos règles de réécriture dans un contexte de niveau répertoire. En particulier, rappelez-vous que le chemin de répertoire sera absent de l'URL que vos règles de réécriture verront. Voici quelques exemples qui permettront de clarifier les choses :

Position de la règle | Règle
Section VirtualHost | RewriteRule "^/images/(.+)\.jpg" "/images/$1.gif"
Fichier .htaccess à la racine des documents | RewriteRule "^images/(.+)\.jpg" "images/$1.gif"
Fichier .htaccess dans le répertoire images | RewriteRule "^(.+)\.jpg" "$1.gif"

Pour une étude plus approfondie de la manière dont mod_rewrite manipule les URLs dans les différents contextes, vous pouvez consulter les entrées du journal générées au cours du processus de réécriture.

Traitement du jeu de règles

Maintenant, quand mod_rewrite se lance dans ces deux phases de l'API, il lit le jeu de règles configurées depuis la structure contenant sa configuration (qui a été elle-même créée soit au démarrage d'Apache pour le contexte du serveur, soit lors du parcours des répertoires par le noyau d'Apache pour le contexte de répertoire). Puis le moteur de réécriture est démarré avec le jeu de règles contenu (une ou plusieurs règles associées à leurs conditions). En lui-même, le mode opératoire du moteur de réécriture d'URLs est exactement le même dans les deux contextes de configuration. Seul le traitement du résultat final diffère.

L'ordre dans lequel les règles sont définies est important car le moteur de réécriture les traite selon une chronologie particulière (et pas très évidente). Le principe est le suivant : le moteur de réécriture traite les règles (les directives RewriteRule) les unes à la suite des autres, et lorsqu'une règle s'applique, il parcourt les éventuelles conditions (directives RewriteConddirectives) associées. Pour des raisons historiques, les conditions précèdent les règles, si bien que le déroulement du contrôle est un peu compliqué. Voir la figure 1 pour plus de détails.

Flux des comparaisons des directives RewriteRule et RewriteCond
Figure 1:Déroulement du contrôle à travers le jeu de règles de réécriture

L'URL est tout d'abord comparée au Modèle de chaque règle. Lorsqu'une règle ne s'applique pas, mod_rewrite stoppe immédiatement le traitement de cette règle et passe à la règle suivante. Si l'URL correspond au Modèle, mod_rewrite recherche la présence de conditions correspondantes (les directives Rewritecond apparaissant dans la configuration juste avant les règles de réécriture). S'il n'y en a pas, mod_rewrite remplace l'URL par une chaîne élaborée à partir de la chaîne de Substitution, puis passe à la règle suivante. Si des conditions sont présentes, mod_rewrite lance un bouclage secondaire afin de les traiter selon l'ordre dans lequel elles sont définies. La logique de traitement des conditions est différente : on ne compare pas l'URL à un modèle. Une chaîne de test TestString est tout d'abord élaborée en développant des variables, des références arrières, des recherches dans des tables de correspondances, etc..., puis cette chaîne de test est comparée au modèle de condition CondPattern. Si le modèle ne correspond pas, les autres conditions du jeu ne sont pas examinées et la règle correspondante ne s'applique pas. Si le modèle correspond, la condition suivante est examinée et ainsi de suite jusqu'à la dernière condition. Si toutes les conditions sont satisfaites, le traitement de la règle en cours se poursuit avec le remplacement de l'URL par la chaîne de Substitution.


Apache et le Chiffrement SSL/TLS - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Apache et le Chiffrement SSL/TLS

Le module mod_ssl du serveur HTTP Apache fournit une interface avec la bibliothèque OpenSSL, qui permet d'effectuer un chiffrement fort en s'appuyant sur les protocoles "Couche Points d'accès Sécurisés" (Secure Sockets Layer - SSL) et "Sécurité de la Couche Transport" (Transport Layer Security - TLS).

Documentation

  • Comment configurer SSL ?
  • Introduction à SSL
  • Compatibilité
  • Foire aux questions
  • Glossaire

mod_ssl

La documentation complète sur les directives et les variables d'environnement fournies par ce module se trouve dans la documentation de référence de mod_ssl.


Chiffrement SSL/TLS fort : Introduction - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > SSL/TLS

Chiffrement SSL/TLS fort : Introduction

Ce chapitre en guise d'introduction est destiné aux lecteurs pour lesquels le Web, HTTP et Apache sont familiers, mais ne sont pas des experts en matière de sécurité. Il n'a pas la prétention d'être un guide détaillé sur le protocole SSL, il ne traitera pas non plus des techniques spécifiques de gestion des certificats dans une organisation, ni des importants problèmes légaux de brevets ou des restrictions d'importation ou d'exportation. Il se veut plutôt une base de travail pour les utilisateurs de mod_ssl en rassemblant différents concepts, définitions et exemples comme point de départ pour une exploration plus détaillée.

Techniques de chiffrement

La maîtrise de SSL nécessite la compréhension des algorithmes de chiffrement, des fonctions relatives aux empreintes de messages (comme les fonctions de type hash ou non réversibles), et des signatures numériques. Ces techniques pourraient faire l'objet d'un ouvrage à elles seules (voir par exemple [AC96]) et constituent les bases de la confidentialité, de l'intégrité et de l'authentification.

Algorithmes de chiffrement

Supposons qu'Alice veuille envoyer un message à sa banque pour transférer une certaine somme. Alice souhaiterait que le message soit privé, car il contient des informations comme son numéro de compte et le montant du transfert. Une solution consisterait à utiliser un algorithme de chiffrement, technique qui permet de remplacer un message par sa version chiffrée, illisible jusqu'à ce qu'elle soit déchiffrée. Sous sa forme chiffrée, le message ne peut être déchiffré qu'en utilisant une clé secrète. Sans la clé, le message est inutilisable : les bons algorithmes de chiffrement rendent si difficile la restitution du texte original par des intrus que ceux-ci y gaspilleraient leurs efforts.

Il existe deux catégories d'algorithmes de chiffrement : conventionnel ou à clé publique.

Chiffrement conventionnel
aussi connu sous le nom de chiffrement symétrique, il nécessite le partage d'une clé entre l'expéditeur et le destinataire : une portion d'information secrète permettant de chiffrer et déchiffrer un message. Tant que cette clé reste secrète, personne à part l'expéditeur et le destinataire ne peut lire le message. Si Alice et sa banque partagent une clé secrète, ils peuvent donc s'envoyer l'un à l'autre des messages privés. Le fait de partager une clé entre l'expéditeur et le destinataire avant de communiquer, tout en la maintenant secrète vis à vis des autres, peut toutefois poser des problèmes.
Chiffrement à clé publique
aussi connu sous le nom de chiffrement asymétrique, il résoud le problème d'échange de clé en définissant un algorithme qui utilise deux clés, chacune d'entre elles pouvant être utilisée pour chiffrer un message. Si une des clés a été utilisée pour chiffrer le message, on doit utiliser l'autre clé pour le déchiffrer. Il est ainsi possible de recevoir des messages sécurisés simplement en rendant publique une des clés (la clé publique), et en gardant l'autre clé secrète (la clé privée).

Tout le monde peut chiffrer un message en utilisant la clé publique, mais seul le propriétaire de la clé privée sera en mesure de le lire. De cette façon, Alice peut envoyer des messages privés au propriétaire d'une paire de clés (sa banque), en les chiffrant à l'aide de la clé publique. Seule la banque sera en mesure de les déchiffrer.

Empreinte d'un message

Bien qu'Alice puisse chiffrer son message pour le rendre privé, il subsiste toujours le risque que quelqu'un puisse modifier le message original ou le remplacer par un autre, afin d'effectuer le transfert de fonds à son profit, par exemple. Une solution pour garantir l'intégrité du message consisterait pour Alice à créer un résumé concentré de son message qu'elle enverrait à sa banque avec ce dernier. A la réception du message, la banque crée son propre résumé et le compare avec celui qu'Alice a envoyé. Si les deux résumés sont identiques, le message reçu n'a pas été modifié.

Un résumé tel que celui-ci est appelé empreinte numérique de message (message digest), fonction irréversible (one-way function) ou fonction de hashage (hash function). Une empreinte de message constitue une représentation courte et de longueur fixe, d'un message plus long et de longueur variable. Les algorithmes de création d'empreintes sont conçus pour produire une empreinte unique pour chaque message. Les empreintes de messages sont conçues pour que la restitution du message à partir de l'empreinte soit d'une difficulté insurmontable, et qu'il soit (en théorie) impossible de trouver deux messages différents qui produisent la même empreinte -- ce qui élimine la possibilité de remplacer un message par un autre en conservant la même empreinte.

Trouver le moyen d'envoyer l'empreinte de manière sécurisée à la banque constitue un autre défit auquel Alice doit faire face ; si l'empreinte n'est pas envoyée de manière sécurisée, son intégrité peut être compromise, et avec elle, la possibilité pour la banque de vérifier l'intégrité du message original. L'intégrité du message ne peut être vérifiée que si l'empreinte qui lui est associée est envoyée de manière sécurisée.

Une solution pour envoyer l'empreinte de manière sécurisée consiste à l'inclure dans une signature numérique.

Signatures numériques

Quand Alice envoie un message à sa banque, cette dernière doit s'assurer que le message a bien été envoyé par elle, pour éviter qu'un intrus puisse effectuer une transaction sur son compte. Une signature numérique, créée par Alice et incluse dans le message, permet d'atteindre cet objectif.

Les signatures numériques peuvent être créées en chiffrant une empreinte de message, ainsi que d'autres informations (comme un numéro d'ordre) avec la clé privée de l'expéditeur. Bien que tout le monde puisse déchiffrer la signature à l'aide de la clé publique, seul l'expéditeur connait la clé privée. Ce qui implique que seul l'expéditeur peut avoir signé le message. Inclure l'empreinte dans la signature entraîne que cette dernière n'est valable que pour ce message ; ceci assure aussi l'intégrité du message car personne ne peut modifier l'empreinte et ensuite signer le message.

Afin de se prémunir contre l'interception et la réutilisation de la signature par un intrus quelques jours plus tard, la signature contient un numéro d'ordre unique. Ceci protège la banque contre une plainte frauduleuse de la part d'Alice alléguant qu'elle n'a pas envoyé le message -- elle seule peut l'avoir signé (non-répudiation).

Certificats

Bien qu'Alice soit parvenue à envoyer un message privé à sa banque, après l'avoir signé et avoir ainsi assuré l'intégrité du message, elle doit encore vérifier qu'elle communique réellement avec la banque. C'est à dire qu'elle doit s'assurer que la clé publique qu'elle utilise appartient bien à la paire de clés de la banque, et non à celle d'un intrus. De même, la banque doit vérifier que la signature du message a bien été construite avec la clé privée d'Alice.

Si chaque partie possède un certificat qui valide l'identité de l'autre, confirme la clé publique, et est signé par un organisme de confiance, alors les deux protagonistes peuvent être sûrs que la personne avec laquelle ils communiquent est bien celle avec laquelle ils désirent le faire. Un tel organisme de confiance s'appelle une Autorité de Certification, et on utilise les certificats à des fins d'authentification.

Contenu d'un certificat

Un certificat associe une clé publique avec l'identité réelle d'un individu, d'un serveur, ou d'une autre entité plus connue sous le nom de sujet. Comme on le voit dans le Tableau 1, les information concernant le sujet comprennent des informations d'identification (le nom distinctif ou distinguished name - dn), ainsi que la clé publique. Il comporte aussi l'identification et la signature de l'autorité de certification qui a délivré le certificat, ainsi que la période de validité de ce dernier. Il peut aussi contenir des informations supplémentaires (ou extensions) telles que des informations de gestion destinées à l'autorité de certification, comme un numéro de série.

Tableau 1: Information contenues dans un certificat

Sujet | Nom distinctif, Clé publique
Fournisseur | Nom distinctif, Signature
Période de validité | Pas avant, Pas après
Informations de gestion | Version, Numéro de série
Extensions | Contraintes de base, Drapeaux Netscape, etc.

Un nom distinctif sert à fournir une identité dans un contexte spécifique -- par exemple, un individu peut posséder un certificat personnel, et aussi un certificat en tant qu'employé. Les noms distinctifs doivent respecter le standard X509 [X509], qui définit les champs, les noms de champs, et les abréviations utilisées pour faire référence aux champs (voir Tableau 2).

Tableau 2: Informations contenues dans le nom distinctif

Champ du DN | Abrév. | Description | Exemple
Nom complet (Common Name) | CN | Nom certifié | CN=Joe Average
Organisation or Entreprise | O | Nom est associé à cette organisation | O=Snake Oil, Ltd.
Unité organisationnelle (Organizational Unit) | OU | Nom est associé avec cette unité organisationnelle, par exemple un département | OU=Research Institute
Ville/Localisation | L | Nom est localisé dans cette ville | L=Snake City
Etat/Province | ST | Nom est localisé dans cet état/province | ST=Desert
Pays | C | Nom est localisé dans ce pays (code ISO) | C=XZ

Une autorité de certification peut définir une contrainte spécifiant quels champs du nom distinctif sont optionnels et lesquels sont obligatoires. Elle peut aussi imposer des contraintes sur le contenu des champs, ce que peuvent aussi faire les utilisateurs de certificats. Par exemple, un navigateur Netscape peut exiger, dans le cas d'un certificat de serveur, que le nom complet (Common Name) corresponde à un nom générique contenant le nom de domaine du serveur, comme *.snakeoil.com.

Le format binaire d'un certificat est défini en utilisant la notation ASN.1 [ASN1] [PKCS]. Cette notation definit la manière de spécifier les contenus, et les règles d'encodage définissent la manière dont ces information sont converties au format binaire. L'encodage binaire du certificat est défini par les Règles d'Encodage Distinctives (Distinguished Encoding Rules - DER), qui se basent d'une manière plus générale sur les Règles d'Encodage de Base (Basic Encoding Rules - BER). Pour les transmissions qui ne supportent pas le format binaire, ce dernier peut être converti au format ASCII en utilisant le codage Base64 [MIME]. Lorsqu'il est placé entre des délimiteurs de début et de fin (comme ci-dessous), on dit que le certificat est encodé au format PEM ("Privacy Enhanced Mail").

Exemple de certificat encodé au format PEM (snakeoil.crt)

-----BEGIN CERTIFICATE-----
MIIC7jCCAlegAwIBAgIBATANBgkqhkiG9w0BAQQFADCBqTELMAkGA1UEBhMCWFkx
FTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25ha2UgVG93bjEXMBUG
A1UEChMOU25ha2UgT2lsLCBMdGQxHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhv
cml0eTEVMBMGA1UEAxMMU25ha2UgT2lsIENBMR4wHAYJKoZIhvcNAQkBFg9jYUBz
bmFrZW9pbC5kb20wHhcNOTgxMDIxMDg1ODM2WhcNOTkxMDIxMDg1ODM2WjCBpzEL
MAkGA1UEBhMCWFkxFTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25h
a2UgVG93bjEXMBUGA1UEChMOU25ha2UgT2lsLCBMdGQxFzAVBgNVBAsTDldlYnNl
cnZlciBUZWFtMRkwFwYDVQQDExB3d3cuc25ha2VvaWwuZG9tMR8wHQYJKoZIhvcN
AQkBFhB3d3dAc25ha2VvaWwuZG9tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB
gQDH9Ge/s2zcH+da+rPTx/DPRp3xGjHZ4GG6pCmvADIEtBtKBFAcZ64n+Dy7Np8b
vKR+yy5DGQiijsH1D/j8HlGE+q4TZ8OFk7BNBFazHxFbYI4OKMiCxdKzdif1yfaa
lWoANFlAzlSdbxeGVHoT0K+gT5w3UxwZKv2DLbCTzLZyPwIDAQABoyYwJDAPBgNV
HRMECDAGAQH/AgEAMBEGCWCGSAGG+EIBAQQEAwIAQDANBgkqhkiG9w0BAQQFAAOB
gQAZUIHAL4D09oE6Lv2k56Gp38OBDuILvwLg1v1KL8mQR+KFjghCrtpqaztZqcDt
2q2QoyulCgSzHbEGmi0EsdkPfg6mp0penssIFePYNI+/8u9HT4LuKMJX15hxBam7
dUHzICxBVC1lnHyYGjDuAMhe396lYAn8bCld1/L4NMGBCQ==
-----END CERTIFICATE-----

Autorités de certification

En vérifiant les informations contenues dans une demande de certificat avant de l'accorder, l'autorité de certification s'assure de l'identité du propriétaire de la clé privée issue de sa paire de clés. Par exemple, Si Alice demande un certificat personnel, l'autorité de certification doit d'abord s'assurer qu'elle correspond vraiment à la personne à laquelle la demande de certificat fait référence.

Chaînes de certification

Une autorité de certification peut aussi émettre un certificat à destination d'une autre autorité de certification. Pour vérifier un certificat, Alice peut être amenée à vérifier le certificat de l'émetteur pour chaque autorité de certification parente, jusqu'à ce qu'elle en atteigne une en qui elle a confiance. Elle peut aussi ne faire confiance qu'aux certificats faisant l'objet d'une chaîne limitée d'émetteurs, afin de réduire le risque de rencontrer un "mauvais" certificat dans la chaîne.

Création d'une autorité de certification racine

Comme indiqué plus haut, chaque certificat nécessite la validation de l'identité du sujet par un émetteur de certificats de niveau supérieur, et ceci en remontant jusqu'à l'Autorité de Certification (CA) racine. Ceci pose un problème : qui va se porter garant du certificat de l'autorité racine qui ne possède pas d'émetteur de certificat ? C'est uniquement dans ce cas que le certificat est auto-signé, l'émetteur du certificat et son sujet étant confondus. Les navigateurs sont préconfigurés avec une liste d'autorités de certification de confiance, mais il est important d'être extrèmement prudent avant de faire confiance à un certificat auto-signé. La large publication d'une clé publique par l'autorité racine réduit cependant les risques encourus en faisant confiance à cette clé -- si quelqu'un publiait une clé en se faisant passer pour l'autorité, il serait vite démasqué.

Quelques compagnies, comme Thawte et VeriSign, se sont proclamées elles-mêmes Autorités de Certification. Ces compagnies proposent les services suivant :

  • Vérification des demandes de certificats
  • Traitement des demandes de certificats
  • Emission et gestion des certificats

Vous pouvez aussi créer votre propre autorité de certification. Bien que risqué dans l'environnement de l'Internet, ceci peut s'avérer utile dans un Intranet, où l'organisme peut vérifier facilement les identités des individus et des serveurs.

Gestion des certificats

Constituer une autorité de certification représente une responsabilité qui nécessite une solide infrastructure administrative, technique et gestionnaire. Les autorités de certification ne se contentent pas d'émettre des certificats, elles doivent aussi les gérer -- à savoir elles déterminent leur durée de validité, elles les renouvellent, et elles maintiennent des listes de certificats qui ont été émis dans le passé mais ne sont plus valides (Listes de révocations de certificats, ou CRLs).

Par exemple, si Alice est titulaire d'un certificat en tant qu'employée d'une compagnie, mais vient de quitter cette compagnie, son certificat doit être révoqué. Comme les certificats ne sont émis qu'après vérification de l'identité du sujet, et peuvent être envoyés à tous ceux avec lesquels le sujet peut communiquer, il est impossible de discerner à partir du seul certificat s'il a été révoqué. Pour vérifier la validité d'un certificat, il est donc nécessaire de contacter l'autorité de certification qui l'a émis afin de pouvoir consulter ses listes de révocations de certificats -- ce qui n'est en général pas une partie automatique du processus.

Note

Si votre autorité de certification ne fait pas partie de la liste des autorités de confiance de votre navigateur, il faut enregistrer le certificat de l'autorité de certification dans ce dernier, ce qui lui permettra de valider les certificats de serveurs signés par cette autorité de certification. Ceci peut être dangereux, car une fois le certificat enregistré, le navigateur acceptera tous les certificats signés par cette autorité de certification.

Couche Points d'Accès Sécurisés - Secure Sockets Layer (SSL)

Le protocole Couche Points d'Accès Sécurisés est une couche protocolaire qui pourrait s'intercaler entre un protocole d'une couche réseau orientée connexion (comme TCP/IP) et une couche protocolaire d'application (comme HTTP). SSL fournit une communication sécurisée entre client et serveur en permettant l'authentification mutuelle, l'utilisation des signatures numériques pour la vérification de l'intégrité des données, et le chiffrement pour la confidentialité.

Ce protocole est conçu pour supporter un grand choix d'algorithmes spécifiques utilisés pour la cryptographie, les empreintes et les signatures. Ceci permet la sélection d'un algorithme pour des serveurs spécifiques en respectant la légalité, les règles d'exportation ou autres contraintes, et permet aussi au protocole de tirer parti des nouveaux algorithmes. Ces choix font l'objet d'une négociation entre client et serveur lors de l'établissement de la session protocolaire.

Tableau 4: Versions du protocole SSL

Version | Source | Description
SSL v2.0 | Standard du fournisseur (de Netscape Corp.) | Premier protocole SSL pour lequel il existe des implémentations
SSL v3.0 | Projet Internet arrivé à expiration (de Netscape Corp.) [SSL3] | Comporte des révisions permettant de prévenir certaines attaques de sécurité spécifiques, ajout de chiffrements non RSA, et support des chaînes de certification
TLS v1.0 | Standard proposé pour l'Internet (de l'IETF) [TLS1] | Révision de SSL 3.0 pour mettre à jour la couche MAC vers HMAC, ajout du bourrage de bloc pour le chiffrement de bloc, standardisation de l'ordonnancement des messages et plus de messages d'alerte.
TLS v1.1 | Standard proposé pour l'Internet (de l'IETF) [TLS11] | Mise à jour de TLS 1.0 pour la protection contre les attaques de type Cipher block chaining (CBC).
TLS v1.2 | Standard proposé pour l'Internet (de l'IETF) [TLS12] | Mise à jour de TLS 1.1 rendant les condensés MD5 obsolètes, et introduisant une incompatibilité avec SSL ce qui interdit toute négociation en vue d'une utilisation de SSLv2.

Il existe plusieurs versions du protocole SSL, comme le montre le Tableau 4. Comme indiqué dans ce dernier, un des apports de SSL 3.0 est le support du chargement des chaînes de certification. Cette fonctionnalité permet à un serveur de passer au navigateur un certificat de serveur accompagné du certificat de l'émetteur. Le chargement de la chaîne permet aussi au navigateur de valider le certificat du serveur, même si les certificats de l'autorité de certification ne sont pas installés pour les émetteurs intermédiaires, car ils sont inclus dans la chaîne de certification. SSL 3.0 sert de base au standard du protocole Sécurité de la Couche Transport ou Transport Layer Security [TLS], actuellement en développement au sein de l'Internet Engineering Task Force (IETF).

Etablissement d'une session

La session SSL est établie en suivant une séquence d'échanges d'informations entre client et serveur, comme le montre la Figure 1. Cette séquence peut varier, selon que le serveur est configuré pour fournir un certificat de serveur ou réclame un certificat client. Bien que dans certains cas, des étapes d'échanges d'informations supplémentaires soient nécessaires pour la gestion des informations de chiffrement, cet article résume un scénario courant. Se reporter aux spécifications SSL pour avoir la liste de toutes les possibilités.

Note

Une fois la session SSL établie, elle peut être réutilisée. Ceci permet d'éviter la perte de performances due à la répétition des nombreuses étapes nécessaires à l'établissement d'une session. Pour parvenir à ceci, le serveur assigne un identifiant de session unique à chaque session SSL ; cet identifiant est mis en cache dans le serveur et le client peut l'utiliser pour des connexions ultérieures afin de réduire la durée des échanges d'informations (et ceci jusqu'à ce que l'identifiant de session arrive à expiration dans le cache du serveur).

Figure 1 : Séquence simplifiée d'échanges d'informations SSL

Les éléments de la séquence d'échanges d'informations, tels qu'ils sont utilisés par le client et le serveur, sont énumérés ci-après :

  1. Négociation de la suite de chiffrement à utiliser durant le transfert des données
  2. Elaboration et échange d'une clé de session entre le client et le serveur
  3. Authentification éventuelle du serveur par le client
  4. Authentification éventuelle du client par le serveur

La première étape, la négociation de la suite de chiffrement, permet au client et au serveur de choisir une suite de chiffrement qu'ils supportent tous les deux. La spécification du protocole SSL 3.0 définit 31 suites de chiffrement. Une suite de chiffrement se compose des éléments suivants :

  • Méthode d'échange de la clé
  • Chiffrement du transfert des données
  • Empreinte du message servant à créer le code d'authentification du message (MAC)

Ces trois éléments sont décrits dans les sections suivantes.

Méthode d'échange de la clé

La méthode d'échange de la clé définit la manière dont la clé de chiffrement symétrique secrète et partagée utilisée pour le transfert des données de l'application sera acceptée par le client et le serveur. SSL 2.0 utilise l'échange de clé RSA seulement, tandis que SSL 3.0 supporte tout un choix d'algorithmes d'échange de clé incluant l'échange de clé RSA (quand les certificats sont utilisés), et l'échange de clés Diffie-Hellman (pour échanger des clés sans certificat, ou en l'absence de communication préalable entre le client et le serveur).

Les signatures numériques constituent une variante dans le choix des méthodes d'échange de clé -- utiliser les signatures ou pas, et dans l'affirmative, quel genre de signatures utiliser. La signature à l'aide d'une clé privée fournit une protection contre une attaque "man-in-the-middle" au cours de laquelle l'échange d'informations destiné à générer la clé partagée peut être intercepté [AC96, p516].

Chiffrement du transfert de données

Comme décrit plus haut, SSL utilise le chiffrement symétrique conventionnel pour chiffrer les messages au cours d'une session. Il existe neuf choix possibles pour le chiffrement, y compris l'option du transfert non chiffré :

  • Pas de chiffrement
  • Chiffrement en continu (Stream Ciphers)
    • RC4 avec clés de 40 bits
    • RC4 avec clés de 128 bits
  • Chiffrement par blocs CBC (CBC Block Ciphers)
    • RC2 avec clé de 40 bits
    • DES avec clé de 40 bits
    • DES avec clé de 56 bits
    • Triple-DES avec clé de 168 bits
    • Idea (clé de 128 bits)
    • Fortezza (clé de 96 bits)

"CBC" signifie Cipher Block Chaining (Chaînage de blocs chiffrés), c'est à dire qu'une portion du bloc de texte chiffré précédent est utilisée pour le chiffrement du bloc courant. "DES" signifie Data Encryption Standard (Standard de Chiffrement des Données) [AC96, ch12], et possède de nombreuses variantes (telles que DES40 et 3DES_EDE). Parmi les algorithmes disponibles, "Idea" est actuellement un des meilleurs et des plus puissants sur le plan cryptographique, et "RC2" est un algorithme propriétaire de RSA DSI [AC96, ch13].

Fonction de création d'empreinte

Le choix d'une fonction de création d'empreinte détermine la manière dont une empreinte est créée à partir d'une unité de données. SSL supporte les fonctions suivantes :

  • Pas d'empreinte (choix Null)
  • MD5, une empreinte de 128 bits
  • Algorithme d'Empreinte Sécurisée (Secure Hash Algorithm - SHA-1), une empreinte de 160 bits

On utilise l'empreinte de message pour créer un Code d'Authentification de Message (Message Authentication Code - MAC) qui est chiffré avec le message afin de vérifier son intégrité et de se protéger contre les attaques de type "rejeu".

Protocole de la séquence d'échanges d'informations

La séquence d'échanges d'informations utilise trois protocoles :

  • Le Protocole d'échanges d'informations SSL pour établir la session SSl entre le client et le serveur.
  • Le Protocole de spécification du chiffrement SSL pour l'agrément effectif de la suite de chiffrement à utiliser pour la session.
  • Le Protocole d'alertes SSL pour la transmission de messages d'erreur SSL entre le client et le serveur.

Ces protocoles, ainsi que les données du protocole de l'application, sont encapsulés dans le Protocole d'enregistrement SSL (SSL Record Protocol), comme le montre la Figure 2. Un protocole encapsulé est tranféré en tant que données par le protocole de la couche de niveau inférieur, qui ne se préoccupe pas du contenu des données. Le protocole encapsulé n'a aucune connaissance du protocole sous-jacent.

Figure 2: Pile du protocole SSL

L'encapsulation des protocoles de contrôle SSL dans le protocole d'enregistrement signifie que si une session active est renégociée, les protocoles de contrôle seront transmis de manière sécurisée. S'il n'y avait pas de session préalable, la suite de chiffrement Null est utilisée, ce qui signifie que les messages ne seront pas chiffrés et ne possèderont pas d'empreinte d'intégrité, jusqu'à ce que la session ait été établie.

Transmission des données

Le protocole d'enregistrement SSL, comme le montre la Figure 3, est utilisé pour transmettre les données de l'application et les données de contrôle SSL entre le client et le serveur, les données étant nécessairement fragmentées en éléments plus petits, ou plusieurs messages de données avec protocole de niveau supérieur pouvant être combinés en un seul élément. Ce protocole peut joindre des signatures d'empreintes, compresser et chiffrer ces éléments avant de les transmettre en utilisant le protocole fiable de transport sous-jacent (Note : actuellement, aucune implémentation majeure de SSL n'inclut le support de la compression).

Figure 3: Protocole d'enregistrement SSL

Sécurisation des communications HTTP

Une des utilisations courantes de SSL est la sécurisation des communication HTTP sur le Web entre un navigateur et un serveur web. Ceci n'exclut pas l'utilisation de HTTP non sécurisé - la version sécurisée (appelée HTTPS) est identique à du vrai HTTP sur SSL, mais utilise le préfixe d'URL https au lieu de http, et un port de serveur différent (par défaut le port 443). Ceci constitue pour une large part ce qu'apporte mod_ssl au serveur web Apache.

Références

[AC96]
Bruce Schneier, Applied Cryptography, 2nd Edition, Wiley, 1996. Voir http://www.counterpane.com/ pour diverses autres productions de Bruce Schneier.
[ASN1]
ITU-T Recommendation X.208, Specification of Abstract Syntax Notation One (ASN.1), dernière mise à jour en 2008. Voir http://www.itu.int/ITU-T/asn1/.
[X509]
ITU-T Recommendation X.509, The Directory - Authentication Framework. A titre de référence, voir http://en.wikipedia.org/wiki/X.509.
[PKCS]
Public Key Cryptography Standards (PKCS), RSA Laboratories Technical Notes, Voir http://www.rsasecurity.com/rsalabs/pkcs/.
[MIME]
N. Freed, N. Borenstein, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, RFC2045. Voir par exemple http://tools.ietf.org/html/rfc2045.
[SSL3]
Alan O. Freier, Philip Karlton, Paul C. Kocher, The SSL Protocol Version 3.0, 1996. Voir http://www.netscape.com/eng/ssl3/draft302.txt.
[TLS1]
Tim Dierks, Christopher Allen, The TLS Protocol Version 1.0, 1999. Voir http://ietf.org/rfc/rfc2246.txt.
[TLS11]
Le protocole TLS Version 1.1, 2006. Voir http://tools.ietf.org/html/rfc4346.
[TLS12]
Le protocole TLS Version 1.2, 2008. Voir http://tools.ietf.org/html/rfc5246.


Chiffrement fort SSL/TLS : Compatibilité - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > SSL/TLS

Chiffrement fort SSL/TLS : Compatibilité

Ce document couvre la compatibilité ascendante entre mod_ssl et d'autres solutions SSL. mod_ssl n'est pas la seule solution SSL pour Apache ; quatre autres produits sont (ou ont été) également disponibles : Apache-SSL, le produit libre de Ben Laurie (d'où mod_ssl est issu à l'origine en 1998), Secure Web Server, un produit commercial de Red Hat (basé sur mod_ssl), Raven SSL Module, un produit commercial de Covalent (basé lui aussi sur mod_ssl), et enfin Stronghold, produit commercial de C2Net et maintenant de Red Hat, (basé sur une branche d'évolution différente appelée Sioux jusqu'à Stronghold 2.x et basé sur mod_ssl depuis Stronghold 3.x).

En plus de ses fonctionnalités propres, mod_ssl rassemble la plupart de celles des autres solutions SSL, si bien qu'il est très simple de migrer depuis un module plus ancien vers mod_ssl. Les directives de configuration et les noms des variables d'environnement utilisés par les solutions SSL plus anciennes diffèrent de ceux qu'utilise mod_ssl ; les tableaux de correspondance ci-dessous fournissent les équivalences de termes utilisés par mod_ssl.

Directives de configuration

La correspondance entre les directives de configuration qu'utilise Apache-SSL 1.x et mod_ssl 2.0.x est fournie dans le Tableau 1. La correspondance depuis Sioux 1.x et Stronghold 2.x n'est que partielle car certaines fonctionnalités de ces interfaces ne sont pas supportées par mod_ssl.

Tableau 1: Correspondance entre les directives de configuration

Ancienne directive | Directive mod_ssl | Commentaires
Compatibilité entre Apache-SSL 1.x et mod_ssl 2.0.x :
SSLEnable | SSLEngine on | plus compacte
SSLDisable | SSLEngine off | plus compacte
SSLLogFile file |  | Utilisez plutôt la directive de niveau module LogLevel.
SSLRequiredCiphers spec | SSLCipherSuite spec | renommée
SSLRequireCipher c1 ... | SSLRequire %{SSL_CIPHER} in {"c1", ...} | plus générale
SSLBanCipher c1 ... | SSLRequire not (%{SSL_CIPHER} in {"c1", ...}) | plus générale
SSLFakeBasicAuth | SSLOptions +FakeBasicAuth | rassemblées
SSLCacheServerPath dir | - | fonctionnalité supprimée
SSLCacheServerPort integer | - | fonctionnalité supprimée
Compatibilité avec Apache-SSL 1.x :
SSLExportClientCertificates | SSLOptions +ExportCertData | rassemblées
SSLCacheServerRunDir dir | - | fonctionnalité non supportée
Compatibilité avec Sioux 1.x :
SSL_CertFile file | SSLCertificateFile file | renommée
SSL_KeyFile file | SSLCertificateKeyFile file | renommée
SSL_CipherSuite arg | SSLCipherSuite arg | renommée
SSL_X509VerifyDir arg | SSLCACertificatePath arg | renommée
SSL_Log file | - | Utilisez plutôt la directive de niveau module LogLevel
SSL_Connect flag | SSLEngine flag | renommée
SSL_ClientAuth arg | SSLVerifyClient arg | renommée
SSL_X509VerifyDepth arg | SSLVerifyDepth arg | renommée
SSL_FetchKeyPhraseFrom arg | - | pas de véritable équivalent ; utiliser SSLPassPhraseDialog
SSL_SessionDir dir | - | pas de véritable équivalent ; utiliser SSLSessionCache
SSL_Require expr | - | pas de véritable équivalent ; utiliser SSLRequire
SSL_CertFileType arg | - | fonctionnalité non supportée
SSL_KeyFileType arg | - | fonctionnalité non supportée
SSL_X509VerifyPolicy arg | - | fonctionnalité non supportée
SSL_LogX509Attributes arg | - | fonctionnalité non supportée
Compatibilité avec Stronghold 2.x :
StrongholdAccelerator engine | SSLCryptoDevice engine | renommée
StrongholdKey dir | - | sans objet
StrongholdLicenseFile dir | - | sans objet
SSLFlag flag | SSLEngine flag | renommée
SSLSessionLockFile file | SSLMutex file | renommée
SSLCipherList spec | SSLCipherSuite spec | renommée
RequireSSL | SSLRequireSSL | renommée
SSLErrorFile file | - | fonctionnalité non supportée
SSLRoot dir | - | fonctionnalité non supportée
SSL_CertificateLogDir dir | - | fonctionnalité non supportée
AuthCertDir dir | - | fonctionnalité non supportée
SSL_Group name | - | fonctionnalité non supportée
SSLProxyMachineCertPath dir | SSLProxyMachineCertificatePath dir | renommée
SSLProxyMachineCertFile file | SSLProxyMachineCertificateFile file | renommée
SSLProxyCipherList spec | SSLProxyCipherSpec spec | renommée

Variables d'environnement

La correspondance entre les noms des variables d'environnement utilisés par les solutions SSL plus anciennes et les noms utilisés par mod_ssl est fournie dans le Tableau 2.

Tableau 2: Dérivation des variables d'environnement

Ancienne variable | Variable mod_ssl | Commentaires
SSL_PROTOCOL_VERSION | SSL_PROTOCOL | renommée
SSLEAY_VERSION | SSL_VERSION_LIBRARY | renommée
HTTPS_SECRETKEYSIZE | SSL_CIPHER_USEKEYSIZE | renommée
HTTPS_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renommée
HTTPS_CIPHER | SSL_CIPHER | renommée
HTTPS_EXPORT | SSL_CIPHER_EXPORT | renommée
SSL_SERVER_KEY_SIZE | SSL_CIPHER_ALGKEYSIZE | renommée
SSL_SERVER_CERTIFICATE | SSL_SERVER_CERT | renommée
SSL_SERVER_CERT_START | SSL_SERVER_V_START | renommée
SSL_SERVER_CERT_END | SSL_SERVER_V_END | renommée
SSL_SERVER_CERT_SERIAL | SSL_SERVER_M_SERIAL | renommée
SSL_SERVER_SIGNATURE_ALGORITHM | SSL_SERVER_A_SIG | renommée
SSL_SERVER_DN | SSL_SERVER_S_DN | renommée
SSL_SERVER_CN | SSL_SERVER_S_DN_CN | renommée
SSL_SERVER_EMAIL | SSL_SERVER_S_DN_Email | renommée
SSL_SERVER_O | SSL_SERVER_S_DN_O | renommée
SSL_SERVER_OU | SSL_SERVER_S_DN_OU | renommée
SSL_SERVER_C | SSL_SERVER_S_DN_C | renommée
SSL_SERVER_SP | SSL_SERVER_S_DN_SP | renommée
SSL_SERVER_L | SSL_SERVER_S_DN_L | renommée
SSL_SERVER_IDN | SSL_SERVER_I_DN | renommée
SSL_SERVER_ICN | SSL_SERVER_I_DN_CN | renommée
SSL_SERVER_IEMAIL | SSL_SERVER_I_DN_Email | renommée
SSL_SERVER_IO | SSL_SERVER_I_DN_O | renommée
SSL_SERVER_IOU | SSL_SERVER_I_DN_OU | renommée
SSL_SERVER_IC | SSL_SERVER_I_DN_C | renommée
SSL_SERVER_ISP | SSL_SERVER_I_DN_SP | renommée
SSL_SERVER_IL | SSL_SERVER_I_DN_L | renommée
SSL_CLIENT_CERTIFICATE | SSL_CLIENT_CERT | renommée
SSL_CLIENT_CERT_START | SSL_CLIENT_V_START | renommée
SSL_CLIENT_CERT_END | SSL_CLIENT_V_END | renommée
SSL_CLIENT_CERT_SERIAL | SSL_CLIENT_M_SERIAL | renommée
SSL_CLIENT_SIGNATURE_ALGORITHM | SSL_CLIENT_A_SIG | renommée
SSL_CLIENT_DN | SSL_CLIENT_S_DN | renommée
SSL_CLIENT_CN | SSL_CLIENT_S_DN_CN | renommée
SSL_CLIENT_EMAIL | SSL_CLIENT_S_DN_Email | renommée
SSL_CLIENT_O | SSL_CLIENT_S_DN_O | renommée
SSL_CLIENT_OU | SSL_CLIENT_S_DN_OU | renommée
SSL_CLIENT_C | SSL_CLIENT_S_DN_C | renommée
SSL_CLIENT_SP | SSL_CLIENT_S_DN_SP | renommée
SSL_CLIENT_L | SSL_CLIENT_S_DN_L | renommée
SSL_CLIENT_IDN | SSL_CLIENT_I_DN | renommée
SSL_CLIENT_ICN | SSL_CLIENT_I_DN_CN | renommée
SSL_CLIENT_IEMAIL | SSL_CLIENT_I_DN_Email | renommée
SSL_CLIENT_IO | SSL_CLIENT_I_DN_O | renommée
SSL_CLIENT_IOU | SSL_CLIENT_I_DN_OU | renommée
SSL_CLIENT_IC | SSL_CLIENT_I_DN_C | renommée
SSL_CLIENT_ISP | SSL_CLIENT_I_DN_SP | renommée
SSL_CLIENT_IL | SSL_CLIENT_I_DN_L | renommée
SSL_EXPORT | SSL_CIPHER_EXPORT | renommée
SSL_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renommée
SSL_SECKEYSIZE | SSL_CIPHER_USEKEYSIZE | renommée
SSL_SSLEAY_VERSION | SSL_VERSION_LIBRARY | renommée
SSL_STRONG_CRYPTO | - | Non supportée par mod_ssl
SSL_SERVER_KEY_EXP | - | Non supportée par mod_ssl
SSL_SERVER_KEY_ALGORITHM | - | Non supportée par mod_ssl
SSL_SERVER_KEY_SIZE | - | Non supportée par mod_ssl
SSL_SERVER_SESSIONDIR | - | Non supportée par mod_ssl
SSL_SERVER_CERTIFICATELOGDIR | - | Non supportée par mod_ssl
SSL_SERVER_CERTFILE | - | Non supportée par mod_ssl
SSL_SERVER_KEYFILE | - | Non supportée par mod_ssl
SSL_SERVER_KEYFILETYPE | - | Non supportée par mod_ssl
SSL_CLIENT_KEY_EXP | - | Non supportée par mod_ssl
SSL_CLIENT_KEY_ALGORITHM | - | Non supportée par mod_ssl
SSL_CLIENT_KEY_SIZE | - | Non supportée par mod_ssl

Fonctions de personnalisation des journaux

Quand mod_ssl est activé, le Format de journal courant (Custom Log Format) du module mod_log_config possède des fonctions supplémentaires comme indiqué dans le chapitre de référence. En plus de la fonction de format étendu ``%{varname}x'' que l'on peut utiliser pour extraire le contenu d'une variable fournie par n'importe quel module, la fonction de format cryptographique ``%{name}c'' a été ajoutée à des fins de compatibilité ascendante. Les appels de fonctions actuellement implémentés sont énumérés dans le Tableau 3.

Table 3: Fonctions cryptographiques du format de journal courant

Appel de fonction | Description
%...{version}c | Version du protocole SSL
%...{cipher}c | Chiffrement SSL
%...{subjectdn}c | Nom distinctif du sujet du certificat du client
%...{issuerdn}c | Nom distinctif de l'émetteur du certificat du client
%...{errcode}c | Erreur lors de la vérification du certificat (numérique)
%...{errstr}c | Erreur lors de la vérification du certificat (chaîne de caractères)


Chiffrement fort SSL/TLS : Mode d'emploi - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > SSL/TLS

Chiffrement fort SSL/TLS : Mode d'emploi

Ce document doit vous permettre de démarrer et de faire fonctionner une configuration de base. Avant de vous lancer dans l'application de techniques avancées, il est fortement recommandé de lire le reste de la documentation SSL afin d'en comprendre le fonctionnement de manière plus approfondie.

Exemple de configuration basique

Votre configuration SSL doit comporter au moins les directives suivantes :

LoadModule ssl_module modules/mod_ssl.so

Listen 443
<VirtualHost *:443>
    ServerName www.example.com
    SSLEngine on
    SSLCertificateFile "/path/to/www.example.com.cert"
    SSLCertificateKeyFile "/path/to/www.example.com.key"
</VirtualHost>

Suites de chiffrement et mise en application de la sécurité de haut niveau

  • Comment créer un serveur SSL qui n'accepte que le chiffrement fort ?
  • Comment créer un serveur qui accepte tous les types de chiffrement en général, mais exige un chiffrement fort pour pouvoir accéder à une URL particulière ?

Comment créer un serveur SSL qui n'accepte que le chiffrement fort ?

Les directives suivantes ne permettent que les chiffrements de plus haut niveau :

SSLCipherSuite HIGH:!aNULL:!MD5

Avec la configuration qui suit, vous indiquez une préférence pour des algorityhmes de chiffrement spécifiques optimisés en matière de rapidité (le choix final sera opéré par mod_ssl, dans la mesure ou le client les supporte) :

SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
SSLHonorCipherOrder on

Comment créer un serveur qui accepte tous les types de chiffrement en général, mais exige un chiffrement fort pour pouvoir accéder à une URL particulière ?

Dans ce cas bien évidemment, une directive SSLCipherSuite au niveau du serveur principal qui restreint le choix des suites de chiffrement aux versions les plus fortes ne conviendra pas. mod_ssl peut cependant être reconfiguré au sein de blocs Location qui permettent d'adapter la configuration générale à un répertoire spécifique ; mod_ssl peut alors forcer automatiquement une renégociation des paramètres SSL pour parvenir au but recherché. Cette configuration peut se présenter comme suit :

# soyons très tolérant a priori
SSLCipherSuite ALL:!aNULL:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL

<Location "/strong/area">
# sauf pour https://hostname/strong/area/ et ses sous-répertoires
# qui exigent des chiffrements forts
SSLCipherSuite HIGH:!aNULL:!MD5
</Location>

Agrafage OCSP

Le protocole de contrôle du statut des certificats en ligne (Online Certificate Status Protocol - OCSP) est un mécanisme permettant de déterminer si un certificat a été révoqué ou non, et l'agrafage OCSP en est une fonctionnalité particulière par laquelle le serveur, par exemple httpd et mod_ssl, maintient une liste des réponses OCSP actuelles pour ses certificats et l'envoie aux clients qui communiquent avec lui. La plupart des certificats contiennent l'adresse d'un répondeur OCSP maintenu par l'Autorité de Certification (CA) spécifiée, et mod_ssl peut requérir ce répondeur pour obtenir une réponse signée qui peut être envoyée aux clients qui communiquent avec le serveur.

L'agrafage OCSP est la méthode la plus performante pour obtenir le statut d'un certificat car il est disponible au niveau du serveur, et le client n'a donc pas besoin d'ouvrir une nouvelle connexion vers l'autorité de certification. Autres avantages de l'absence de communication entre le client et l'autorité de certification : l'autorité de certification n'a pas accès à l'historique de navigation du client, et l'obtention du statut du certificat est plus efficace car elle n'est plus assujettie à une surcharge éventuelle des serveurs de l'autorité de certification.

La charge du serveur est moindre car la réponse qu'il a obtenu du répondeur OCSP peut être réutilisée par tous les clients qui utilisent le même certificat dans la limite du temps de validité de la réponse.

Une fois le support général SSL correctement configuré, l'activation de l'agrafage OCSP ne requiert que des modifications mineures à la configuration de httpd et il suffit en général de l'ajout de ces deux directives :

SSLUseStapling On
SSLStaplingCache "shmcb:ssl_stapling(32768)"

Ces directives sont placées de façon à ce qu'elles aient une portée globale (et particulièrement en dehors de toute section VirtualHost), le plus souvent où sont placées les autres directives de configuration globales SSL, comme conf/extra/httpd-ssl.conf pour les installations de httpd à partir des sources, ou /etc/apache2/mods-enabled/ssl.conf pour Ubuntu ou Debian, etc...

Le chemin spécifié par la directive SSLStaplingCache (par exemple logs/) doit être le même que celui spécifié par la directive SSLSessionCache. Ce chemin est relatif au chemin spécifié par la directive ServerRoot.

Cette directive SSLStaplingCache particulière nécessite le chargement du module mod_socache_shmcb (à cause du préfixe shmcb de son argument). Ce module est en général déjà activé pour la directive SSLSessionCache, ou pour des modules autres que mod_ssl. Si vous activez un cache de session SSL utilisant un mécanisme autre que mod_socache_shmcb, utilisez aussi ce mécanisme alternatif pour la directive SSLStaplingCache. Par exemple :

SSLSessionCache "dbm:ssl_scache"
SSLStaplingCache "dbm:ssl_stapling"

Vous pouvez utiliser la commande openssl pour vérifier que votre serveur envoie bien une réponse OCSP :

$ openssl s_client -connect www.example.com:443 -status -servername www.example.com
...
OCSP response:
======================================
OCSP Response Data:
    OCSP Response Status: successful (0x0)
    Response Type: Basic OCSP Response
...
    Cert Status: Good
...

Les sections suivantes explicitent les situations courantes qui requièrent des modifications supplémentaires de la configuration. Vous pouvez aussi vous référer au manuel de référence de mod_ssl.

Si l'on utilise plus que quelques certificats SSL pour le serveur

Les réponses OCSP sont stockées dans le cache d'agrafage SSL. Alors que les réponses ont une taille de quelques centaines à quelques milliers d'octets, mod_ssl supporte des réponses d'une taille jusqu'à environ 10 ko. Dans notre cas, le nombre de certificats est conséquent et la taille du cache (32768 octets dans l'exemple ci-dessus) doit être augmentée. En cas d'erreur lors du stockage d'une réponse, le message AH01929 sera enregistré dans le journal.

Si le certificat ne spécifie pas de répondeur OCSP, ou si une adresse différente doit être utilisée

Veuillez vous référer à la documentation de la directive SSLStaplingForceURL.

Vous pouvez vérifier si un certificat spécifie un répondeur OCSP en utilisant la commande openssl comme suit :

$ openssl x509 -in ./www.example.com.crt -text | grep 'OCSP.*http'
OCSP - URI:http://ocsp.example.com

Si un URI OCSP est fourni et si le serveur web peut communiquer directement avec lui sans passer par un mandataire, aucune modification supplémentaire de la configuration n'est requise. Notez que les règles du pare-feu qui contrôlent les connexions sortantes en provenance du serveur web devront peut-être subir quelques ajustements.

Si aucun URI OCSP n'est fourni, contactez votre autorité de certification pour savoir s'il en existe une ; si c'est le cas, utilisez la directive SSLStaplingForceURL pour la spécifier dans la configuration du serveur virtuel qui utilise le certificat.

Si plusieurs serveurs virtuels sont configurés pour utiliser SSL et si l'agrafage OCSP doit être désactivé pour certains d'entre eux

Ajoutez la directive SSLUseStapling Off à la configuration des serveurs virtuels pour lesquels l'agrafage OCSP doit être désactivé.

Si le répondeur OCSP est lent ou instable

De nombreuses directives permettent de gérer les temps de réponse et les erreurs. Référez-vous à la documentation de SSLStaplingFakeTryLater, SSLStaplingResponderTimeout, et SSLStaplingReturnResponderErrors.

Si mod_ssl enregistre l'erreur AH02217 dans le journal

AH02217: ssl_stapling_init_cert: Can't retrieve issuer certificate!

Afin de pouvoir supporter l'agrafage OCSP lorsqu'un certificat de serveur particulier est utilisé, une chaîne de certification pour ce certificat doit être spécifiée. Si cela n'a pas été fait lors de l'activation de SSL, l'erreur AH02217 sera enregistrée lorsque l'agrafage OCSP sera activé, et les clients qui utilisent le certificat considéré ne recevront pas de réponse OCSP.

Veuillez vous référer à la documentation des directives SSLCertificateChainFile et SSLCertificateFile pour spécifier une chaîne de certification.

Authentification du client et contrôle d'accès

  • Comment forcer les clients à s'authentifier à l'aide de certificats ?
  • Comment forcer les clients à s'authentifier à l'aide de certificats pour une URL particulière, mais autoriser quand-même tout client anonyme à accéder au reste du serveur ?
  • Comment n'autoriser l'accès à une URL particulière qu'aux clients qui possèdent des certificats, mais autoriser l'accès au reste du serveur à tous les clients ?
  • Comment imposer HTTPS avec chiffrements forts, et soit authentification de base, soit possession de certificats clients, pour l'accès à une partie de l'Intranet, pour les clients en provenance de l'Internet ?

Comment forcer les clients à s'authentifier à l'aide de certificats ?

Lorsque vous connaissez tous vos clients (comme c'est en général le cas au sein d'un intranet d'entreprise), vous pouvez imposer une authentification basée uniquement sur les certificats. Tout ce dont vous avez besoin pour y parvenir est de créer des certificats clients signés par le certificat de votre propre autorité de certification (ca.crt), et d'authentifier les clients à l'aide de ces certificats.

# exige un certificat client signé par le certificat de votre CA
# contenu dans ca.crt
SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile "conf/ssl.crt/ca.crt"

Comment forcer les clients à s'authentifier à l'aide de certificats pour une URL particulière, mais autoriser quand-même tout client anonyme à accéder au reste du serveur ?

Pour forcer les clients à s'authentifier à l'aide de certificats pour une URL particulière, vous pouvez utiliser les fonctionnalités de reconfiguration de mod_ssl en fonction du répertoire :

SSLVerifyClient none
SSLCACertificateFile "conf/ssl.crt/ca.crt"

<Location "/secure/area">
SSLVerifyClient require
SSLVerifyDepth 1
</Location>

Comment n'autoriser l'accès à une URL particulière qu'aux clients qui possèdent des certificats, mais autoriser l'accès au reste du serveur à tous les clients ?

La clé du problème consiste à vérifier si une partie du certificat client correspond à ce que vous attendez. Cela signifie en général consulter tout ou partie du nom distinctif (DN), afin de vérifier s'il contient une chaîne connue. Il existe deux méthodes pour y parvenir ; on utilise soit le module mod_auth_basic, soit la directive SSLRequire.

La méthode du module mod_auth_basic est en général incontournable lorsque les certificats ont un contenu arbitraire, ou lorsque leur DN ne contient aucun champ connu (comme l'organisation, etc...). Dans ce cas, vous devez construire une base de données de mots de passe contenant tous les clients autorisés, comme suit :

SSLVerifyClient      none
SSLCACertificateFile "conf/ssl.crt/ca.crt"
SSLCACertificatePath "conf/ssl.crt"

<Directory "/usr/local/apache2/htdocs/secure/area">
SSLVerifyClient      require
    SSLVerifyDepth       5
    SSLOptions           +FakeBasicAuth
    SSLRequireSSL
    AuthName             "Snake Oil Authentication"
    AuthType             Basic
    AuthBasicProvider    file
    AuthUserFile         "/usr/local/apache2/conf/httpd.passwd"
    Require              valid-user
</Directory>

Le mot de passe utilisé dans cet exemple correspond à la chaîne de caractères "password" chiffrée en DES. Voir la documentation de la directive SSLOptions pour plus de détails.

httpd.passwd

/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA

Lorsque vos clients font tous partie d'une même hiérarchie, ce qui apparaît dans le DN, vous pouvez les authentifier plus facilement en utilisant la directive SSLRequire, comme suit :

SSLVerifyClient      none
SSLCACertificateFile "conf/ssl.crt/ca.crt"
SSLCACertificatePath "conf/ssl.crt"

<Directory "/usr/local/apache2/htdocs/secure/area">
  SSLVerifyClient      require
  SSLVerifyDepth       5
  SSLOptions           +FakeBasicAuth
  SSLRequireSSL
  SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
               and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
</Directory>

Comment imposer HTTPS avec chiffrements forts, et soit authentification de base, soit possession de certificats clients, pour l'accès à une partie de l'Intranet, pour les clients en provenance de l'Internet ? Je souhaite quand-même autoriser l'accès en HTTP aux clients de l'intranet.

On suppose dans ces exemples que les clients de l'intranet ont des adresses IP dans la gamme 192.168.1.0/24, et que la partie de l'intranet à laquelle vous voulez autoriser l'accès depuis l'Internet est /usr/local/apache2/htdocs/subarea. Ces lignes de configuration doivent se trouver en dehors de votre hôte virtuel HTTPS, afin qu'elles s'appliquent à la fois à HTTP et HTTPS.

SSLCACertificateFile "conf/ssl.crt/company-ca.crt"

<Directory "/usr/local/apache2/htdocs">
#   En dehors de subarea, seul l'accès depuis l'intranet est
#   autorisé
    Require              ip 192.168.1.0/24
</Directory>

<Directory "/usr/local/apache2/htdocs/subarea">
#   Dans subarea, tout accès depuis l'intranet est autorisé
#   mais depuis l'Internet, seul l'accès par HTTPS + chiffrement fort + Mot de passe
#   ou HTTPS + chiffrement fort + certificat client n'est autorisé.

#   Si HTTPS est utilisé, on s'assure que le niveau de chiffrement est fort.
#   Autorise en plus les certificats clients comme une alternative à
#   l'authentification basique.
    SSLVerifyClient      optional
    SSLVerifyDepth       1
    SSLOptions           +FakeBasicAuth +StrictRequire
    SSLRequire           %{SSL_CIPHER_USEKEYSIZE} >= 128

    #   ON oblige les clients venant d'Internet à utiliser HTTPS
    RewriteEngine        on
    RewriteCond          "%{REMOTE_ADDR}" "!^192\.168\.1\.[0-9]+$"
    RewriteCond          "%{HTTPS}" "!=on"
    RewriteRule          "." "-" [F]

    #   On permet l'accès soit sur les critères réseaux, soit par authentification Basique
    Satisfy              any

    #   Contrôle d'accès réseau
    Require              ip 192.168.1.0/24

    #   Configuration de l'authentification HTTP Basique
    AuthType             basic
    AuthName             "Protected Intranet Area"
    AuthBasicProvider    file
    AuthUserFile         "conf/protected.passwd"
    Require              valid-user
</Directory>

Journalisation

mod_ssl peut enregistrer des informations de débogage très verbeuses dans le journal des erreurs, lorsque sa directive LogLevel est définie à des niveaux de trace élevés. Par contre, sur un serveur très sollicité, le niveau info sera probablement déjà trop élevé. Souvenez-vous que vous pouvez configurer la directive LogLevel par module afin de pourvoir à vos besoins.


Chiffrement SSL/TLS fort: foire aux questions - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > SSL/TLS

Chiffrement SSL/TLS fort: foire aux questions

Le sage n'apporte pas de bonnes réponses, il pose les bonnes questions

-- Claude Levi-Strauss

Installation

  • Pourquoi le démarrage d'Apache provoque-t-il des erreurs de permission en rapport avec SSLMutex ?
  • Pourquoi mod_ssl s'arrête-t-il avec l'erreur "Failed to generate temporary 512 bit RSA private key" au démarrage d'Apache ?

Pourquoi le démarrage d'Apache provoque-t-il des erreurs de permission en rapport avec SSLMutex ?

Des erreurs telles que ``mod_ssl: Child could not open SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (avec l'erreur système qui suit) [...] System: Permission denied (errno: 13)'' sont souvent provoquées par des permissions trop restrictives sur les répertoires parents. Assurez-vous que tous les répertoires parents (ici /opt, /opt/apache et /opt/apache/logs) ont le bit x positionné au moins pour l'UID sous lequel les processus enfants d'Apache s'exécutent (voir la directive User).

Pourquoi mod_ssl s'arrête-t-il avec l'erreur "Failed to generate temporary 512 bit RSA private key" au démarrage d'Apache ?

Pour fonctionner correctement, les logiciels de cryptographie ont besoin d'une source de données aléatoires. De nombreux systèmes d'exploitation libres proposent un "périphérique source d'entropie" qui fournit ce service (il se nomme en général /dev/random). Sur d'autres systèmes, les applications doivent amorcer manuellement le Générateur de Nombres Pseudo-Aléatoires d'OpenSSL (Pseudo Random Number Generator -PRNG) à l'aide de données appropriées avant de générer des clés ou d'effectuer un chiffrement à clé publique. Depuis la version 0.9.5, les fonctions d'OpenSSL qui nécessitent des données aléatoires provoquent une erreur si le PRNG n'a pas été amorcé avec une source de données aléatoires d'au moins 128 bits.

Pour éviter cette erreur, mod_ssl doit fournir suffisamment d'entropie au PRNG pour lui permettre de fonctionner correctement. Ce niveau d'entropie est défini par la directive SSLRandomSeed.

Configuration

  • Peut-on faire cohabiter HTTP et HTTPS sur le même serveur ?
  • Quel port HTTPS utilise-t-il ?
  • Comment s'exprimer en langage HTTPS à des fins de test ?
  • Pourquoi la communication se bloque-t-elle lorsque je me connecte à mon serveur Apache configuré pour SSL ?
  • Pourquoi, lorsque je tente d'accéder en HTTPS à mon serveur Apache+mod_ssl fraîchement installé, l'erreur ``Connection Refused'' s'affiche-t-elle ?
  • Pourquoi les variables SSL_XXX ne sont-elles pas disponibles dans mes scripts CGI et SSI ?
  • Comment puis-je basculer entre les protocoles HTTP et HTTPS dans les hyperliens relatifs ?

Peut-on faire cohabiter HTTP et HTTPS sur le même serveur ?

Oui. HTTP et HTTPS utilisent des ports différents (HTTP écoute le port 80 et HTTPS le port 443), si bien qu'il n'y a pas de conflit direct entre les deux. Vous pouvez soit exécuter deux instances séparées du serveur, chacune d'entre elles écoutant l'un de ces ports, soit utiliser l'élégante fonctionnalité d'Apache que constituent les hôtes virtuels pour créer deux serveurs virtuels gérés par la même instance d'Apache - le premier serveur répondant en HTTP aux requêtes sur le port 80, le second répondant en HTTPS aux requêtes sur le port 443.

Quel port HTTPS utilise-t-il ?

Vous pouvez associer le protocole HTTPS à n'importe quel port, mais le port standard est le port 443, que tout navigateur compatible HTTPS va utiliser par défaut. Vous pouvez forcer votre navigateur à utiliser un port différent en le précisant dans l'URL. Par exemple, si votre serveur est configuré pour servir des pages en HTTPS sur le port 8080, vous pourrez y accéder par l'adresse https://example.com:8080/.

Comment s'exprimer en langage HTTPS à des fins de test ?

Alors que vous utilisez simplement

$ telnet localhost 80
GET / HTTP/1.0

pour tester facilement Apache via HTTP, les choses ne sont pas si simples pour HTTPS à cause du protocole SSL situé entre TCP et HTTP. La commande OpenSSL s_client vous permet cependant d'effectuer un test similaire via HTTPS :

$ openssl s_client -connect localhost:443 -state -debug
GET / HTTP/1.0

Avant la véritable réponse HTTP, vous recevrez des informations détaillées à propos de l'établissement de la connexion SSL. Si vous recherchez un client en ligne de commande à usage plus général qui comprend directement HTTP et HTTPS, qui peut effectuer des opérations GET et POST, peut utiliser un mandataire, supporte les requêtes portant sur une partie d'un fichier (byte-range), etc..., vous devriez vous tourner vers l'excellent outil cURL. Grâce à lui, vous pouvez vérifier si Apache répond correctement aux requêtes via HTTP et HTTPS comme suit :

$ curl http://localhost/
$ curl https://localhost/

Pourquoi la communication se bloque-t-elle lorsque je me connecte à mon serveur Apache configuré pour SSL ?

Ceci peut arriver si vous vous connectez à un serveur HTTPS (ou à un serveur virtuel) via HTTP (par exemple, en utilisant http://example.com/ au lieu de https://example.com). Cela peut aussi arriver en essayant de vous connecter via HTTPS à un serveur HTTP (par exemple, en utilisant https://example.com/ avec un serveur qui ne supporte pas HTTPS, ou le supporte, mais sur un port non standard). Assurez-vous que vous vous connectez bien à un serveur (virtuel) qui supporte SSL.

Pourquoi, lorsque je tente d'accéder en HTTPS à mon serveur Apache+mod_ssl fraîchement installé, l'erreur ``Connection Refused'' s'affiche-t-elle ?

Une configuration incorrecte peut provoquer ce type d'erreur. Assurez-vous que vos directives Listen s'accordent avec vos directives <VirtualHost>. Si l'erreur persiste, recommencez depuis le début en restaurant la configuration par défaut fournie parmod_ssl.

Pourquoi les variables SSL_XXX ne sont-elles pas disponibles dans mes scripts CGI et SSI ?

Assurez-vous que la directive ``SSLOptions +StdEnvVars'' est bien présente dans le contexte de vos requêtes CGI/SSI.

Comment puis-je basculer entre les protocoles HTTP et HTTPS dans les hyperliens relatifs ?

Normalement, pour basculer entre HTTP et HTTPS, vous devez utiliser des hyperliens pleinement qualifiés (car vous devez modifier le schéma de l'URL). Cependant, à l'aide du module mod_rewrite, vous pouvez manipuler des hyperliens relatifs, pour obtenir le même effet.

RewriteEngine on
RewriteRule   "^/(.*)_SSL$"   "https://%{SERVER_NAME}/$1" [R,L]
RewriteRule   "^/(.*)_NOSSL$" "http://%{SERVER_NAME}/$1"  [R,L]

Ce jeu de règles rewrite vous permet d'utiliser des hyperliens de la forme <a href="document.html_SSL"> pour passer en HTTPS dans les liens relatifs. (Remplacez SSL par NOSSL pour passer en HTTP.)

Certificats

  • Qu'est-ce qu'un clé privée RSA, un certificat, une demande de signature de certificat (CSR) ?
  • Y a-t-il une différence au démarrage entre un serveur Apache non SSL et un serveur Apache supportant SSL ?
  • Comment créer un certificat auto-signé SSL à des fins de test ?
  • Comment créer un vrai certificat SSL ?
  • Comment créer et utiliser sa propre Autorité de certification (CA) ?
  • Comment modifier le mot de passe de ma clé privée ?
  • Comment démarrer Apache sans avoir à entrer de mot de passe ?
  • Comment vérifier si une clé privée correspond bien à son certificat ?
  • Comment convertir un certificat du format PEM au format DER ?
  • Pourquoi les navigateurs se plaignent-ils de ne pas pouvoir vérifier mon certificat de serveur ?

Qu'est-ce qu'un clé privée RSA, un certificat, une demande de signature de certificat (CSR) ?

Un fichier de clé privée RSA est un fichier numérique que vous pouvez utiliser pour déchiffrer des messages que l'on vous a envoyés. Il a son pendant à caractère public que vous pouvez distribuer (par le biais de votre certificat), ce qui permet aux utilisateurs de chiffrer les messages qu'ils vous envoient.

Une Demande de Signature de Certificat (CSR) est un fichier numérique qui contient votre clé publique et votre nom. La CSR doit être envoyée à une Autorité de Certification (CA), qui va la convertir en vrai certificat en la signant.

Un certificat contient votre clé publique RSA, votre nom, le nom de la CA, et est signé numériquement par cette dernière. Les navigateurs qui reconnaissent la CA peuvent vérifier la signature du certificat, et ainsi en extraire votre clé publique RSA. Ceci leur permet de vous envoyer des messages chiffrés que vous seul pourrez déchiffrer.

Se référer au chapitre Introduction pour une description générale du protocole SSL.

Y a-t-il une différence au démarrage entre un serveur Apache non SSL et un serveur Apache supportant SSL ?

Oui. En général, avec ou sans mod_ssl intégré, le démarrage d'Apache ne présente pas de différences. Cependant, si votre fichier de clé privée SSL possède un mot de passe, vous devrez le taper au démarrage d'Apache.

Devoir entrer manuellement le mot de passe au démarrage du serveur peut poser quelques problèmes - par exemple, quand le serveur est démarré au moyen de scripts au lancement du système. Dans ce cas, vous pouvez suivre les étapes ci-dessous pour supprimer le mot de passe de votre clé privée. Gardez à l'esprit qu'agir ainsi augmente les risques de sécurité - agissez avec précaution !

Comment créer un certificat auto-signé SSL à des fins de test ?

  1. Vérifiez qu'OpenSSL est installé et l'exécutable openssl dans votre PATH.

  2. Exécuter la commande suivante pour créer les fichiers server.key et server.crt :
    $ openssl req -new -x509 -nodes -out server.crt -keyout server.key
    Ces fichiers seront utilisés comme suit dans votre httpd.conf :
    SSLCertificateFile    "/path/to/this/server.crt"
SSLCertificateKeyFile "/path/to/this/server.key"
  3. Il est important de savoir que le fichier server.key n'a pas de mot de passe. Pour ajouter un mot de passe à la clé, vous devez exécuter la commande suivante et confirmer le mot de passe comme demandé.

    $ openssl rsa -des3 -in server.key -out server.key.new
    $ mv server.key.new server.key

    Sauvegardez le fichier server.key ainsi que son mot de passe en lieu sûr.

Comment créer un vrai certificat SSL ?

Voici la marche à suivre pas à pas :

  1. Assurez-vous qu'OpenSSL est bien installé et dans votre PATH.

  2. Créez une clé privée RSA pour votre serveur Apache (elle sera au format PEM et chiffrée en Triple-DES):

    $ openssl genrsa -des3 -out server.key 2048

    Enregistrez le fichier server.key et le mot de passe éventuellement défini en lieu sûr. Vous pouvez afficher les détails de cette clé privée RSA à l'aide de la commande :

    $ openssl rsa -noout -text -in server.key

    Si nécessaire, vous pouvez aussi créer une version PEM non chiffrée (non recommandé) de clé privée RSA avec :

    $ openssl rsa -in server.key -out server.key.unsecure

  3. Créez une Demande de signature de Certificat (CSR) à l'aide de la clé privée précédemment générée (la sortie sera au format PEM):

    $ openssl req -new -key server.key -out server.csr

    Vous devez entrer le Nom de Domaine Pleinement Qualifié ("Fully Qualified Domain Name" ou FQDN) de votre serveur lorsqu'OpenSSL vous demande le "CommonName", c'est à dire que si vous générez une CSR pour un site web auquel on accèdera par l'URL https://www.foo.dom/, le FQDN sera "www.foo.dom". Vous pouvez afficher les détails de ce CSR avec :

    $ openssl req -noout -text -in server.csr

  4. Vous devez maintenant envoyer la CSR à une Autorité de Certification (CA), afin que cette dernière puisse la signer. Une fois la CSR signée, vous disposerez d'un véritable certificat que vous pourrez utiliser avec Apache. Vous pouvez faire signer votre CSR par une CA commerciale ou par votre propre CA.
    Les CAs commerciales vous demandent en général de leur envoyer la CSR par l'intermédiaire d'un formulaire web, de régler le montant de la signature, puis vous envoient un certificat signé que vous pouvez enregistrer dans un fichier server.crt. Pour plus de détails sur la manière de créer sa propre CA, et de l'utiliser pour signer une CSR, voir ci-dessous.
    Une fois la CSR signée, vous pouvez afficher les détails du certificat comme suit :

    $ openssl x509 -noout -text -in server.crt
  5. Vous devez maintenant disposer de deux fichiers : server.key et server.crt. Ils sont précisés dans votre fichier httpd.conf comme suit :
    SSLCertificateFile    "/path/to/this/server.crt"
SSLCertificateKeyFile "/path/to/this/server.key"
    Le fichier server.csr n'est plus nécessaire.

Comment créer et utiliser sa propre Autorité de certification (CA) ?

La solution la plus simple consiste à utiliser les scripts CA.sh ou CA.pl fournis avec OpenSSL. De préférence, utilisez cette solution, à moins que vous ayez de bonnes raisons de ne pas le faire. Dans ce dernier cas, vous pouvez créer un certificat auto-signé comme suit :

  1. Créez une clé privée RSA pour votre serveur (elle sera au format PEM et chiffrée en Triple-DES) :

    $ openssl genrsa -des3 -out server.key 2048

    Sauvegardez le fichier server.key et le mot de passe éventuellement défini en lieu sûr. Vous pouvez afficher les détails de cette clé privée RSA à l'aide de la commande :

    $ openssl rsa -noout -text -in server.key

    Si nécessaire, vous pouvez aussi créer une version PEM non chiffrée (non recommandé) de cette clé privée RSA avec :

    $ openssl rsa -in server.key -out server.key.unsecure

  2. Créez un certificat auto-signé (structure X509) à l'aide de la clé RSA que vous venez de générer (la sortie sera au format PEM) :

    $ openssl req -new -x509 -nodes -sha1 -days 365 -key server.key -out server.crt -extensions usr_cert

    Cette commande signe le certificat du serveur et produit un fichier server.crt. Vous pouvez afficher les détails de ce certificat avec :

    $ openssl x509 -noout -text -in server.crt

Comment modifier le mot de passe de ma clé privée ?

Vous devez simplement lire la clé avec l'ancien mot de passe et la réécrire en spécifiant le nouveau mot de passe. Pour cela, vous pouvez utiliser les commandes suivantes :

$ openssl rsa -des3 -in server.key -out server.key.new
$ mv server.key.new server.key

La première fois qu'il vous est demandé un mot de passe PEM, vous devez entrer l'ancien mot de passe. Ensuite, on vous demandera d'entrer encore un mot de passe - cette fois, entrez le nouveau mot de passe. Si on vous demande de vérifier le mot de passe, vous devrez entrer le nouveau mot de passe une seconde fois.

Comment démarrer Apache sans avoir à entrer de mot de passe ?

L'apparition de ce dialogue au démarrage et à chaque redémarrage provient du fait que la clé privée RSA contenue dans votre fichier server.key est enregistrée sous forme chiffrée pour des raisons de sécurité. Le déchiffrement de ce fichier nécessite un mot de passe, afin de pouvoir être lu et interprété. Cependant, La suppression du mot de passe diminue le niveau de sécurité du serveur - agissez avec précautions !

  1. Supprimer le chiffrement de la clé privée RSA (tout en conservant une copie de sauvegarde du fichier original) :

    $ cp server.key server.key.org
    $ openssl rsa -in server.key.org -out server.key

  2. Assurez-vous que le fichier server.key n'est lisible que par root :

    $ chmod 400 server.key

Maintenant, server.key contient une copie non chiffrée de la clé. Si vous utilisez ce fichier pour votre serveur, il ne vous demandera plus de mot de passe. CEPENDANT, si quelqu'un arrive à obtenir cette clé, il sera en mesure d'usurper votre identité sur le réseau. Vous DEVEZ par conséquent vous assurer que seuls root ou le serveur web peuvent lire ce fichier (de préférence, démarrez le serveur web sous root et faites le s'exécuter sous un autre utilisateur, en n'autorisant la lecture de la clé que par root).

Une autre alternative consiste à utiliser la directive ``SSLPassPhraseDialog exec:/chemin/vers/programme''. Gardez cependant à l'esprit que ce n'est bien entendu ni plus ni moins sécurisé.

Comment vérifier si une clé privée correspond bien à son certificat ?

Une clé privée contient une série de nombres. Deux de ces nombres forment la "clé publique", les autres appartiennent à la "clé privée". Les bits de la "clé publique" sont inclus quand vous générez une CSR, et font par conséquent partie du certificat associé.

Pour vérifier que la clé publique contenue dans votre certificat correspond bien à la partie publique de votre clé privée, il vous suffit de comparer ces nombres. Pour afficher le certificat et la clé, utilisez cette commande :

$ openssl x509 -noout -text -in server.crt
$ openssl rsa -noout -text -in server.key

Les parties `modulus' et `public exponent' doivent être identiques dans la clé et le certificat. Comme le `public exponent' est habituellement 65537, et comme il est difficile de vérifier visuellement que les nombreux nombres du `modulus' sont identiques, vous pouvez utiliser l'approche suivante :

$ openssl x509 -noout -modulus -in server.crt | openssl md5
$ openssl rsa -noout -modulus -in server.key | openssl md5

Il ne vous reste ainsi que deux nombres relativement courts à comparer. Il est possible, en théorie que ces deux nombres soient les mêmes, sans que les nombres du modulus soient identiques, mais les chances en sont infimes.

Si vous souhaitez vérifier à quelle clé ou certificat appartient une CSR particulière, vous pouvez effectuer le même calcul sur la CSR comme suit :

$ openssl req -noout -modulus -in server.csr | openssl md5

Comment convertir un certificat du format PEM au format DER ?

Le format des certificats par défaut pour OpenSSL est le format PEM, qui est tout simplement un format DER codé en Base64, avec des lignes d'en-têtes et des annotations. Certaines applications, comme Microsoft Internet Explorer, ont besoin d'un certificat au format DER de base. Vous pouvez convertir un fichier PEM cert.pem en son équivalent au format DER cert.der à l'aide de la commande suivante : $ openssl x509 -in cert.pem -out cert.der -outform DER

Pourquoi les navigateurs se plaignent-ils de ne pas pouvoir vérifier mon certificat de serveur ?

Ceci peut se produire si votre certificat de serveur est signé par une autorité de certification intermédiaire. Plusieurs CAs, comme Verisign ou Thawte, ont commencé à signer les certificats avec des certificats intermédiaires au lieu de leur certificat racine.

Les certificats de CA intermédiaires se situe à un niveau intermédiaire entre le certificat racine de la CA (qui est installé dans les navigateurs) et le certificat du serveur (que vous avez installé sur votre serveur). Pour que le navigateur puisse traverser et vérifier la chaîne de confiance depuis le certificat du serveur jusqu'au certificat racine, il faut lui fournir les certificats intermédiaires. Les CAs devraient pouvoir fournir de tels paquetages de certificats intermédiaires à installer sur les serveurs.

Vous devez inclure ces certificats intermédiaires via la directive SSLCertificateChainFile.

Le protocole SSL

  • Pourquoi de nombreuses et aléatoires erreurs de protocole SSL apparaissent-elles en cas de forte charge du serveur ?
  • Pourquoi la charge de mon serveur est-elle plus importante depuis qu'il sert des ressources chiffrées en SSL ?
  • Pourquoi les connexions en HTTPS à mon serveur prennent-elles parfois jusqu'à 30 secondes pour s'établir ?
  • Quels sont les algorithmes de chiffrement supportés par mod_ssl ?
  • Pourquoi une erreur ``no shared cipher'' apparaît-elle quand j'essaie d'utiliser un algorithme de chiffrement Diffie-Hellman anonyme (ADH) ?
  • Pourquoi une erreur ``no shared cipher'' apparaît-elle lorsqu'on se connecte à mon serveur fraîchement installé ?
  • Pourquoi ne peut-on pas utiliser SSL avec des hôtes virtuels identifiés par un nom et non par une adresse IP ?
  • Est-il possible d'utiliser l'hébergement virtuel basé sur le nom d'hôte pour différencier plusieurs hôtes virtuels ?
  • Comment mettre en oeuvre la compression SSL ?
  • Lorsque j'utilise l'authentification de base sur HTTPS, l'icône de verrouillage des navigateurs Netscape reste ouverte quand la boîte de dialogue d'authentification apparaît. Cela signifie-t-il que les utilisateur et mot de passe sont envoyés en clair ?
  • Pourquoi des erreurs d'entrée/sortie apparaissent-elles lorsqu'on se connecte à un serveur Apache+mod_ssl avec Microsoft Internet Explorer (MSIE) ?
  • Comment activer TLS-SRP ?
  • Pourquoi des erreurs de négociation apparaissent avec les clients basés sur Java lorsqu'on utilise un certificat de plus de 1024 bits ?

Pourquoi de nombreuses et aléatoires erreurs de protocole SSL apparaissent-elles en cas de forte charge du serveur ?

Ce problème peut avoir plusieurs causes, mais la principale réside dans le cache de session SSL défini par la directive SSLSessionCache. Le cache de session DBM est souvent à la source du problème qui peut être résolu en utilisant le cache de session SHM (ou en n'utilisant tout simplement pas de cache).

Pourquoi la charge de mon serveur est-elle plus importante depuis qu'il sert des ressources chiffrées en SSL ?

SSL utilise un procédé de chiffrement fort qui nécessite la manipulation d'une quantité très importante de nombres. Lorsque vous effectuez une requête pour une page web via HTTPS, tout (même les images) est chiffré avant d'être transmis. C'est pourquoi un accroissement du traffic HTTPS entraîne une augmentation de la charge.

Pourquoi les connexions en HTTPS à mon serveur prennent-elles parfois jusqu'à 30 secondes pour s'établir ?

Ce problème provient en général d'un périphérique /dev/random qui bloque l'appel système read(2) jusqu'à ce que suffisamment d'entropie soit disponible pour servir la requête. Pour plus d'information, se référer au manuel de référence de la directive SSLRandomSeed.

Quels sont les algorithmes de chiffrement supportés par mod_ssl ?

En général, tous les algorithmes de chiffrement supportés par la version d'OpenSSL installée, le sont aussi par mod_ssl. La liste des algorithmes disponibles peut dépendre de la manière dont vous avez installé OpenSSL. Typiquement, au moins les algorithmes suivants sont supportés :

  1. RC4 avec SHA1
  2. AES avec SHA1
  3. Triple-DES avec SHA1

Pour déterminer la liste réelle des algorithmes disponibles, vous pouvez utiliser la commande suivante :

$ openssl ciphers -v

Pourquoi une erreur ``no shared cipher'' apparaît-elle quand j'essaie d'utiliser un algorithme de chiffrement Diffie-Hellman anonyme (ADH) ?

Par défaut et pour des raisons de sécurité, OpenSSl ne permet pas l'utilisation des algorithmes de chiffrements ADH. Veuillez vous informer sur les effets pervers potentiels si vous choisissez d'activer le support de ces algorithmes de chiffrements.

Pour pouvoir utiliser les algorithmes de chiffrements Diffie-Hellman anonymes (ADH), vous devez compiler OpenSSL avec ``-DSSL_ALLOW_ADH'', puis ajouter ``ADH'' à votre directive SSLCipherSuite.

Pourquoi une erreur ``no shared cipher'' apparaît-elle lorsqu'on se connecte à mon serveur fraîchement installé ?

Soit vous avez fait une erreur en définissant votre directive SSLCipherSuite (comparez-la avec l'exemple préconfiguré dans extra/httpd-ssl.conf), soit vous avez choisi d'utiliser des algorithmes DSA/DH au lieu de RSA lorsque vous avez généré votre clé privée, et avez ignoré ou êtes passé outre les avertissements. Si vous avez choisi DSA/DH, votre serveur est incapable de communiquer en utilisant des algorithmes de chiffrements SSL basés sur RSA (du moins tant que vous n'aurez pas configuré une paire clé/certificat RSA additionnelle). Les navigateurs modernes tels que NS ou IE ne peuvent communiquer par SSL qu'avec des algorithmes RSA. C'est ce qui provoque l'erreur "no shared ciphers". Pour la corriger, générez une nouvelle paire clé/certificat pour le serveur en utilisant un algorithme de chiffrement RSA.

Pourquoi ne peut-on pas utiliser SSL avec des hôtes virtuels identifiés par un nom et non par une adresse IP ?

La raison est très technique, et s'apparente au problème de la primauté de l'oeuf ou de la poule. La couche du protocole SSL se trouve en dessous de la couche de protocole HTTP qu'elle encapsule. Lors de l'établissement d'une connexion SSL (HTTPS), Apache/mod_ssl doit négocier les paramètres du protocole SSL avec le client. Pour cela, mod_ssl doit consulter la configuration du serveur virtuel (par exemple, il doit accéder à la suite d'algorithmes de chiffrement, au certificat du serveur, etc...). Mais afin de sélectionner le bon serveur virtuel, Apache doit connaître le contenu du champ d'en-tête HTTP Host. Pour cela, il doit lire l'en-tête de la requête HTTP. Mais il ne peut le faire tant que la négociation SSL n'est pas terminée, or, la phase de négociation SSL a besoin du nom d'hôte contenu dans l'en-tête de la requête. Voir la question suivante pour contourner ce problème.

Notez que si votre certificat comporte un nom de serveur avec caractères génériques, ou des noms de serveurs multiples dans le champ subjectAltName, vous pouvez utiliser SSL avec les serveurs virtuels à base de noms sans avoir à contourner ce problème.

Est-il possible d'utiliser l'hébergement virtuel basé sur le nom d'hôte pour différencier plusieurs hôtes virtuels ?

L'hébergement virtuel basé sur le nom est une méthode très populaire d'identification des différents hôtes virtuels. Il permet d'utiliser la même adresse IP et le même numéro de port pour de nombreux sites différents. Lorsqu'on se tourne vers SSL, il semble tout naturel de penser que l'on peut appliquer la même méthode pour gérer plusieurs hôtes virtuels SSL sur le même serveur.

C'est possible, mais seulement si on utilise une version 2.2.12 ou supérieure du serveur web compilée avec OpenSSL version 0.9.8j ou supérieure. Ceci est du au fait que l'utilisation de l'hébergement virtuel à base de nom avec SSL nécessite une fonctionnalité appelée Indication du Nom de Serveur (Server Name Indication - SNI) que seules les révisions les plus récentes de la spécification SSL supportent.

Notez que si votre certificat comporte un nom de serveur avec caractères génériques, ou des noms de serveurs multiples dans le champ subjectAltName, vous pouvez utiliser SSL avec les serveurs virtuels à base de noms sans avoir à contourner ce problème.

La raison en est que le protocole SSL constitue une couche séparée qui encapsule le protocole HTTP. Aini, la session SSL nécessite une transaction séparée qui prend place avant que la session HTTP n'ait débuté. Le serveur reçoit une requête SSL sur l'adresse IP X et le port Y (habituellement 443). Comme la requête SSL ne contenait aucun en-tête Host:, le serveur n'avait aucun moyen de déterminer quel hôte virtuel SSL il devait utiliser. En général, il utilisait le premier qu'il trouvait et qui correspondait à l'adresse IP et au port spécifiés.

Par contre, si vous utilisez des versions du serveur web et d'OpenSSL qui supportent SNI, et si le navigateur du client le supporte aussi, alors le nom d'hôte sera inclus dans la requête SSL originale, et le serveur web pourra sélectionner le bon serveur virtuel SSL.

Bien entendu, vous pouvez utiliser l'hébergement virtuel basé sur le nom pour identifier de nombreux hôtes virtuels non-SSL (tous sur le port 80 par exemple), et ne gérer qu'un seul hôte virtuel SSL (sur le port 443). Mais dans ce cas, vous devez définir le numéro de port non-SSL à l'aide de la directive NameVirtualHost dans ce style :

NameVirtualHost 192.168.1.1:80

il existe d'autres solutions alternatives comme :

Utiliser des adresses IP différentes pour chaque hôte SSL. Utiliser des numéros de port différents pour chaque hôte SSL.

Comment mettre en oeuvre la compression SSL ?

Bien que la négociation pour la compression SSL ait été définie dans la spécification de SSLv2 et TLS, ce n'est qu'en mai 2004 que la RFC 3749 a défini DEFLATE comme une méthode de compression standard négociable.

Depuis la version 0.9.8, OpenSSL supporte cette compression par défaut lorsqu'il est compilé avec l'option zlib. Si le client et le serveur supportent la compression, elle sera utilisée. Cependant, la plupart des clients essaient encore de se connecter avec un Hello SSLv2. Comme SSLv2 ne comportait pas de table des algorithmes de compression préférés dans sa négociation, la compression ne peut pas être négociée avec ces clients. Si le client désactive le support SSLv2, un Hello SSLv3 ou TLS peut être envoyé, selon la bibliothèque SSL utilisée, et la compression peut être mise en oeuvre. Vous pouvez vérifier si un client utilise la compression SSL en journalisant la variable %{SSL_COMPRESS_METHOD}x.

Lorsque j'utilise l'authentification de base sur HTTPS, l'icône de verrouillage des navigateurs Netscape reste ouverte quand la boîte de dialogue d'authentification apparaît. Cela signifie-t-il que les utilisateur et mot de passe sont envoyés en clair ?

Non, le couple utilisateur/mot de passe est transmis sous forme chiffrée. L'icône de chiffrement dans les navigateurs Netscape n'est pas vraiment synchronisé avec la couche SSL/TLS. Il ne passe à l'état verrouillé qu'au moment où la première partie des données relatives à la page web proprement dite sont transférées, ce qui peut prêter à confusion. Le dispositif d'authentification de base appartient à la couche HTTP, qui est située au dessus de la couche SSL/TLS dans HTTPS. Avant tout transfert de données HTTP sous HTTPS, la couche SSL/TLS a déjà achevé sa phase de négociation et basculé dans le mode de communication chiffrée. Ne vous laissez donc pas abuser par l'état de cet icône.

Pourquoi des erreurs d'entrée/sortie apparaissent-elles lorsqu'on se connecte via HTTPS à un serveur Apache+mod_ssl avec des versions anciennes de Microsoft Internet Explorer (MSIE) ?

La première raison en est la présence dans l'implémentation SSL de certaines versions de MSIE de bogues subtils en rapport avec le dispositif de "maintien en vie" (keep-alive) HTTP, et les alertes de notification de fermeture de session SSL en cas de coupure de la connexion au point d'entrée (socket). De plus, l'interaction entre SSL et les fonctionnalités HTTP/1.1 pose problème avec certaines versions de MSIE. Vous pouvez contourner ces problèmes en interdisant à Apache l'utilisation de HTTP/1.1, les connexions avec maintien en vie ou l'envoi de messages de notification de fermeture de session SSL aux clients MSIE. Pour cela, vous pouvez utiliser la directive suivante dans votre section d'hôte virtuel avec support SSL :

SetEnvIf User-Agent "MSIE [2-5]" \
         nokeepalive ssl-unclean-shutdown \
         downgrade-1.0 force-response-1.0

En outre, certaines versions de MSIE ont des problèmes avec des algorithmes de chiffrement particuliers. Hélas, il n'est pas possible d'apporter une solution spécifique à MSIE pour ces problèmes, car les algorithmes de chiffrement sont utilisés dès la phase de négociation SSL. Ainsi, une directive SetEnvIf spécifique à MSIE ne peut être d'aucun secours. Par contre, vous devrez ajuster les paramètres généraux de manière drastique. Avant de vous décider, soyez sûr que vos clients rencontrent vraiment des problèmes. Dans la négative, n'effectuez pas ces ajustements car ils affecteront tous vos clients, ceux utilisant MSIE, mais aussi les autres.

Comment activer TLS-SRP ?

Le protocole TLS-SRP (Echange de clés sécurisé par mot de passe pour TLS comme spécifié dans la RFC 5054) peut compléter ou même remplacer les certificats lors du processus d'authentification des connexions SSL. Pour utiliser TLS-SRP, spécifiez un fichier de vérification SRP OpenSSL via la directive SSLSRPVerifierFile. Vous pouvez créer le fichier de vérification via l'utilitaire openssl :

openssl srp -srpvfile passwd.srpv -add username

Une fois ce fichier créé, vous devez le référencer dans la configuration du serveur SSL :

SSLSRPVerifierFile /path/to/passwd.srpv

Pour forcer les clients à utiliser des algorithmes de chiffrement basés sur TLS-SRP et s'affranchissant des certificats, utilisez la directive suivante :

SSLCipherSuite "!DSS:!aRSA:SRP"

Pourquoi des erreurs de négociation apparaissent avec les clients basés sur Java lorsqu'on utilise un certificat de plus de 1024 bits ?

Depuis la version 2.4.7, mod_ssl utilise des paramètres DH qui comportent des nombres premiers de plus de 1024 bits. Cependant, java 7 et ses versions antérieures ne supportent que les nombres premiers DH d'une longueur maximale de 1024 bits.

Si votre client basé sur Java s'arrête avec une exception telle que java.lang.RuntimeException: Could not generate DH keypair et java.security.InvalidAlgorithmParameterException: Prime size must be multiple of 64, and can only range from 512 to 1024 (inclusive), et si httpd enregistre le message tlsv1 alert internal error (SSL alert number 80) dans son journal des erreurs (avec un LogLevel info ou supérieur), vous pouvez soit réarranger la liste d'algorithmes de mod_ssl via la directive SSLCipherSuite (éventuellement en conjonction avec la directive SSLHonorCipherOrder), soit utiliser des paramètres DH personnalisés avec un nombre premier de 1024 bits, paramètres qui seront toujours prioritaires par rapport à tout autre paramètre DH par défaut.

Pour générer des paramètres DH personnalisés, utilisez la commande openssl dhparam 1024. Vous pouvez aussi utiliser les paramètres DH standards issus de la RFC 2409, section 6.2 :

-----BEGIN DH PARAMETERS-----
MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR
Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL
/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC
-----END DH PARAMETERS-----

Ajoute les paramètres personnalisés incluant les lignes "BEGIN DH PARAMETERS" et "END DH PARAMETERS" à la fin du premier fichier de certificat défini via la directive SSLCertificateFile.

Support de mod_ssl

  • Quelles sont les sources d'informations disponibles en cas de problème avec mod_ssl ?
  • Qui peut-on contacter pour un support en cas de problème avec mod_ssl ?
  • Quelles informations dois-je fournir lors de l'écriture d'un rapport de bogue ?
  • Un vidage mémoire s'est produit, pouvez-vous m'aider ?
  • Comment puis-je obtenir une journalisation de ce qui s'est passé, pour m'aider à trouver la raison de ce vidage mémoire ?

Quelles sont les sources d'informations disponibles en cas de problème avec mod_ssl ?

Voici les sources d'informations disponibles ; vous devez chercher ici en cas de problème.

Vous trouverez des réponses dans la Foire Aux Questions du manuel utilisateur (ce document)
http://httpd.apache.org/docs/2.4/ssl/ssl_faq.html
Cherchez tout d'abord dans la foire aux questions (ce document). Si votre question est courante, on a déjà dû y répondre de nombreuses fois, et elle fait probablement partie de ce document.

Qui peut-on contacter pour un support en cas de problème avec mod_ssl ?

Voici toutes les possibilités de support pour mod_ssl, par ordre de préférence. Merci d'utiliser ces possibilités dans cet ordre - ne vous précipitez pas sur celle qui vous paraît la plus alléchante.

  1. Envoyez un rapport de problème à la liste de diffusion de support des utilisateurs d'Apache httpd
    users@httpd.apache.org
    C'est la deuxième manière de soumettre votre rapport de problème. Ici aussi, vous devez d'abord vous abonner à la liste, mais vous pourrez ensuite discuter facilement de votre problème avec l'ensemble de la communauté d'utilisateurs d'Apache httpd.
  2. Ecrire un rapport de problème dans la base de données des bogues
    http://httpd.apache.org/bug_report.html
    C'est la dernière manière de soumettre votre rapport de problème. Vous ne devez utiliser cette solution que si vous avez déjà écrit aux listes de diffusion, et n'avez pas trouvé de solution. Merci de suivre les instructions de la page mentionnée ci-dessus avec soin.

Quelles informations dois-je fournir lors de l'écriture d'un rapport de bogue ?

Vous devez toujours fournir au moins les informations suivantes :

Les versions d'Apache httpd et OpenSSL installées
La version d'Apache peut être déterminée en exécutant httpd -v. La version d'OpenSSL peut être déterminée en exécutant openssl version. Si Lynx est installé, vous pouvez aussi exécuter la commandelynx -mime_header http://localhost/ | grep Server et ainsi obtenir ces informations en une seule fois.
Les détails de votre installation d'Apache httpd et OpenSSL
A cet effet, vous pouvez fournir un fichier journal de votre session de terminal qui montre les étapes de la configuration et de l'installation. En cas d'impossibilité, vous devez au moins fournir la ligne de commande configure que vous avez utilisée.
En cas de vidage mémoire, inclure une trace de ce qui s'est passé
Si votre serveur Apache httpd fait un vidage de sa mémoire, merci de fournir en pièce jointe un fichier contenant une trace de la zone dédiée à la pile (voir ci-dessous pour des informations sur la manière de l'obtenir). Il est nécessaire de disposer de ces informations afin de pouvoir déterminer la raison de votre vidage mémoire.
Une description détaillée de votre problème
Ne riez pas, nous sommes sérieux ! De nombreux rapports n'incluent pas de description de la véritable nature du problème. Sans ces informations, il est très difficile pour quiconque de vous aider. Donc, et c'est votre propre intérêt (vous souhaitez que le problème soit résolu, n'est-ce pas ?), fournissez, s'il vous plait, le maximum de détails possible. Bien entendu, vous devez aussi inclure tout ce qui a été dit précédemment.

Un vidage mémoire s'est produit, pouvez-vous m'aider ?

En général non, du moins tant que vous n'aurez pas fourni plus de détails à propos de la localisation dans le code où Apache a effectué son vidage mémoire. Ce dont nous avons en général besoin pour vous aider est une trace de ce qui s'est passé (voir la question suivante). Sans cette information, il est pratiquement impossible de déterminer la nature du problème et de vous aider à le résoudre.

Comment puis-je obtenir une journalisation de ce qui s'est passé, pour m'aider à trouver la raison de ce vidage mémoire ?

Vous trouverez ci-dessous les différentes étapes permettant d'obtenir une journalisation des évènements (backtrace) :

  1. Assurez-vous que les symboles de débogage sont disponibles, au moins pour Apache. Pour cela, sur les plates-formes où GCC/GDB est utilisé, vous devez compiler Apache+mod_ssl avec l'option ``OPTIM="-g -ggdb3"''. Sur les autres plates-formes, l'option ``OPTIM="-g"'' est un minimum.
  2. Démarrez le serveur et essayez de reproduire le vidage mémoire. A cet effet, vous pouvez utiliser une directive du style ``CoreDumpDirectory /tmp'' pour être sûr que le fichier de vidage mémoire puisse bien être écrit. Vous devriez obtenir un fichier /tmp/core ou /tmp/httpd.core. Si ce n'est pas le cas, essayez de lancer votre serveur sous un UID autre que root. Pour des raisons de sécurité, de nombreux noyaux modernes de permettent pas à un processus de vider sa mémoire une fois qu'il a accompli un setuid() (à moins qu'il effectue un exec()) car des informations d'un niveau privilégié pourraient être transmises en mémoire. Si nécessaire, vous pouvez exécuter /chemin/vers/httpd -X manuellement afin de ne pas permettre à Apache de se clôner (fork).
  3. Analysez le vidage mémoire. Pour cela, exécutez gdb /path/to/httpd /tmp/httpd.core ou une commande similaire. Dans GDB, tout ce que vous avez à faire est d'entrer bt, et voila, vous obtenez la backtrace. Pour les débogueurs autres que GDB consulter le manuel correspondant.


How-To / Tutoriels - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

How-To / Tutoriels

How-To / Tutoriels

Authentification et autorisation

L'authentification représente tout processus par lequel vous vérifiez si quelqu'un correspond bien à la personne qu'il prétend être. L'autorisation représente tout processus permettant de savoir si une personne est autorisée à aller là où elle veut aller, ou à obtenir les informations qu'elle demande.

Voir Authentification, Autorisation

Contrôle d'accès

Le contrôle d'accès se réfère au processus permettant d'interdire ou d'accorder l'accès à une ressource en fonction de certains critères, et il existe de nombreuses façons d'y parvenir.

Voir Contrôle d'accès

Contenu dynamique avec CGI

L'interface CGI (Common Gateway Interface) fournit au serveur web une méthode d'interaction avec des programmes externes générateurs de contenu, souvent nommés programmes CGI ou scripts CGI. Il s'agit d'une méthode simple permettant d'ajouter du contenu dynamique à votre site web. Ce document se veut une introduction à la configuration de CGI sur votre serveur web Apache et à l'écriture de programmes CGI.

Voir CGI : contenu dynamique

Fichiers .htaccess

Les fichiers .htaccess permettent de modifier la configuration du serveur au niveau de chaque répertoire. À cet effet, un fichier est placé dans un répertoire particulier du site web, et les directives de configuration qu'il contient s'appliquent à ce répertoire et à tous ses sous-répertoires.

Voir Fichiers .htaccess

HTTP/2 avec httpd

HTTP/2 est une évolution du protocole de la couche application le plus connu au monde, HTTP. Les efforts se sont concentrés sur une amélioration de l'efficacité de l'utilisation des ressources réseau sans modifier la sémantique de HTTP. Ce guide explique la manière dont HTTP/2 est implémenté dans httpd, donne des conseils pour une configuration de base ainsi qu'une liste de recommandations.

Voir le guide HTTP/2

Introduction au Inclusions côté Serveur (Server Side Includes ou SSI)

Les SSI sont des directives que l'on place dans des pages HTML, et qui sont évaluées par le serveur lorsque ces pages sont servies. Elles vous permettent d'ajouter du contenu généré dynamiquement à une page HTML existante, sans avoir à servir l'intégralité de la page via un programme CGI, ou toute autre technologie dynamique.

Voir Server Side Includes (SSI)

Répertoires web de l'utilisateur

Sur les systèmes multi-utilisateurs, vous pouvez permettre à chaque utilisateur d'avoir un site web dans son répertoire home via la directive UserDir. Les visiteurs de l'URL http://example.com/~nom-utilisateur/ vont recevoir du contenu situé dans le répertoire home de l'utilisateur "nom-utilisateur", et dans le sous-répertoire spécifié par la directive UserDir.

Voir Répertoires web des utilisateurs (public_html)

Mandataires inverses

Apache httpd possède des fonctionnalités évoluées de serveur mandataire inverse via ses directives ProxyPass et BalancerMember qui permettent d'implémenter un système de mandataire inverse sophistiqué garantissant une haute disponibilité, une répartition et une réattribution de charge, un regroupement de serveurs en grappe (clustering) basé sur le cloud et une reconfiguration dynamique à la volée.

Voir le Guide de configuration des mandataires inverses

Réécriture d'URLs avec mod_rewrite

La réécriture d'URLs avec (ou sans) mod_rewrite devient l'une des questions les plus fréquentes posées dans nos listes de diffusion et nos canaux IRC. C'est pourquoi nous avons dédié une section entière de notre documentation à des howtos et recettes sur ce sujet.


Authentification et autorisation - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Recettes / Tutoriels

Authentification et autorisation

L'authentification est un processus qui vous permet de vérifier qu'une personne est bien celle qu'elle prétend être. L'autorisation est un processus qui permet à une personne d'aller là où elle veut aller, ou d'obtenir les informations qu'elle désire.

Pour le contrôle d'accès en général, voir le How-To Contrôle d'accès.

Modules et directives concernés

Trois groupes de modules sont concernés par le processus d'authentification et d'autorisation. Vous devrez utiliser au moins un module de chaque groupe.

  • Type d'authentification (voir la directive AuthType)
    • mod_auth_basic
    • mod_auth_digest
  • Fournisseur d'authentification (voir les directives AuthBasicProvider et AuthDigestProvider)
    • mod_authn_anon
    • mod_authn_dbd
    • mod_authn_dbm
    • mod_authn_file
    • mod_authnz_ldap
    • mod_authn_socache
  • Autorisation (voir la directive Require)
    • mod_authnz_ldap
    • mod_authz_dbd
    • mod_authz_dbm
    • mod_authz_groupfile
    • mod_authz_host
    • mod_authz_owner
    • mod_authz_user

On peut aussi ajouter mod_authn_core et mod_authz_core. Ces modules implémentent des directives générales qui opèrent au dessus de tous les modules d'authentification.

Le module mod_authnz_ldap est un fournisseur d'authentification et d'autorisation. Le module mod_authz_host fournit une autorisation et un contrôle d'accès basés sur le nom du serveur, l'adresse IP ou certaines caractéristiques de la requête, mais ne fait pas partie du système fournisseur d'authentification. Le module mod_access_compat a été créé à des fins de compatibilité ascendante avec mod_access.

Vous devriez aussi jeter un coup d'oeil au manuel de recettes de Contrôle d'accès, qui décrit les différentes méthodes de contrôle d'accès à votre serveur.

Introduction

Si votre site web contient des informations sensibles ou destinées seulement à un groupe de personnes restreint, les techniques exposées dans cet article vont vous aider à vous assurer que les personnes qui ont accès à ces pages sont bien celles auxquelles vous avez donné l'autorisation d'accès.

Cet article décrit les méthodes "standards" de protection de parties de votre site web que la plupart d'entre vous sont appelés à utiliser.

Note :

Si vos données ont un réel besoin de sécurisation, prévoyez l'utilisation de mod_ssl en plus de toute méthode d'authentification.

Les prérequis

Les directives décrites dans cet article devront être insérées soit au niveau de la configuration de votre serveur principal (en général dans une section <Directory>), soit au niveau de la configuration des répertoires (fichiers .htaccess)

Si vous envisagez l'utilisation de fichiers .htaccess, la configuration de votre serveur devra permettre l'ajout de directives d'authentification dans ces fichiers. Pour ce faire, on utilise la directive AllowOverride, qui spécifie quelles directives pourront éventuellement contenir les fichiers de configuration de niveau répertoire.

Comme il est ici question d'authentification, vous aurez besoin d'une directive AllowOverride du style :

AllowOverride AuthConfig

Si vous avez l'intention d'ajouter les directives directement dans le fichier de configuration principal, vous devrez bien entendu posséder les droits en écriture sur ce fichier.

Vous devrez aussi connaître un tant soit peu la structure des répertoires de votre serveur, ne serait-ce que pour savoir où se trouvent certains fichiers. Cela ne devrait pas présenter de grandes difficultés, et nous essaierons de clarifier tout ça lorsque le besoin s'en fera sentir.

Enfin, vous devrez vous assurer que les modules mod_authn_core et mod_authz_core ont été soit compilés avec le binaire httpd, soit chargés par le fichier de configuration httpd.conf. Ces deux modules fournissent des directives générales et des fonctionnalités qui sont critiques quant à la configuration et l'utilisation de l'authentification et de l'autorisation au sein du serveur web.

Mise en oeuvre

Nous décrivons ici les bases de la protection par mot de passe d'un répertoire de votre serveur.

Vous devez en premier lieu créer un fichier de mots de passe. La méthode exacte selon laquelle vous allez créer ce fichier va varier en fonction du fournisseur d'authentification choisi. Mais nous entrerons dans les détails plus loin, et pour le moment, nous nous contenterons d'un fichier de mots de passe en mode texte.

Ce fichier doit être enregistré à un endroit non accessible depuis le web, de façon à ce que les clients ne puissent pas le télécharger. Par exemple, si vos documents sont servis à partir de /usr/local/apache/htdocs, vous pouvez enregistrer le fichier des mots de passe dans /usr/local/apache/passwd.

L'utilitaire htpasswd fourni avec Apache permet de créer ce fichier. Vous le trouverez dans le répertoire bin de votre installation d'Apache. Si vous avez installé Apache à partir d'un paquetage tiers, il sera probablement dans le chemin par défaut de vos exécutables.

Pour créer le fichier, tapez :

htpasswd -c /usr/local/apache/passwd/passwords rbowen

htpasswd vous demandera d'entrer le mot de passe, et de le retaper pour confirmation :

# htpasswd -c /usr/local/apache/passwd/passwords rbowen
New password: mot-de-passe
Re-type new password: mot-de-passe
Adding password for user rbowen

Si htpasswd n'est pas dans le chemin par défaut de vos exécutables, vous devrez bien entendu entrer le chemin complet du fichier. Dans le cas d'une installation par défaut, il se trouve à /usr/local/apache2/bin/htpasswd.

Ensuite, vous allez devoir configurer le serveur de façon à ce qu'il demande un mot de passe et lui préciser quels utilisateurs ont l'autorisation d'accès. Pour ce faire, vous pouvez soit éditer le fichier httpd.conf, soit utiliser un fichier .htaccess. Par exemple, si vous voulez protéger le répertoire /usr/local/apache/htdocs/secret, vous pouvez utiliser les directives suivantes, soit dans le fichier /usr/local/apache/htdocs/secret/.htaccess, soit dans le fichier httpd.conf à l'intérieur d'une section <Directory "/usr/local/apache/htdocs/secret"> :

AuthType Basic
AuthName "Restricted Files"
# (Following line optional)
AuthBasicProvider file
AuthUserFile "/usr/local/apache/passwd/passwords"
Require user rbowen

Examinons ces directives une à une. La directive AuthType définit la méthode utilisée pour authentifier l'utilisateur. La méthode la plus courante est Basic, et elle est implémentée par mod_auth_basic. Il faut cependant garder à l'esprit que l'authentification Basic transmet le mot de passe depuis le client vers le serveur en clair. Cette méthode ne devra donc pas être utilisée pour la transmission de données hautement sensibles si elle n'est pas associée au module mod_ssl. Apache supporte une autre méthode d'authentification : AuthType Digest. Cette méthode est implémentée par le module mod_auth_digest et a été conçue pour améliorer la sécurité. Ce but n'a cependant pas été atteint et il est préférable de chiffrer la connexion avec mod_ssl.

La directive AuthName définit l'Identificateur (Realm) à utiliser avec l'authentification. L'identificateur possède deux fonctions. Tout d'abord, le client présente en général cette information à l'utilisateur dans le cadre de la boîte de dialogue de mot de passe. Ensuite, le client l'utilise pour déterminer quel mot de passe envoyer pour une zone authentifiée donnée.

Ainsi par exemple, une fois un client authentifié dans la zone "Fichiers réservés", il soumettra à nouveau automatiquement le même mot de passe pour toute zone du même serveur marquée de l'identificateur "Fichiers réservés". De cette façon, vous pouvez éviter à un utilisateur d'avoir à saisir plusieurs fois le même mot de passe en faisant partager le même identificateur entre plusieurs zones réservées. Bien entendu et pour des raisons de sécurité, le client devra redemander le mot de passe chaque fois que le nom d'hôte du serveur sera modifié.

La directive AuthBasicProvider est, dans ce cas, facultative, car file est la valeur par défaut pour cette directive. Par contre, cette directive sera obligatoire si vous utilisez une autre source d'authentification comme mod_authn_dbm ou mod_authn_dbd.

La directive AuthUserFile définit le chemin du fichier de mots de passe que nous venons de créer avec htpasswd. Si vous possédez un grand nombre d'utilisateurs, la durée de la recherche dans un fichier texte pour authentifier un utilisateur à chaque requête va augmenter rapidement, et pour pallier cet inconvénient, Apache peut aussi stocker les données relatives aux utilisateurs dans des bases de données rapides. Le module mod_authn_dbm fournit la directive AuthDBMUserFile. Les programmes dbmmanage et htdbm permettent de créer et manipuler ces fichiers. Vous trouverez de nombreuses options d'autres types d'authentification fournies par des modules tiers dans la Base de données des modules d'Apache.

Enfin, la directive Require implémente la partie autorisation du processus en définissant l'utilisateur autorisé à accéder à cette zone du serveur. Dans la section suivante, nous décrirons les différentes méthodes d'utilisation de la directive Require.

Autorisation d'accès à plusieurs personnes

Les directives ci-dessus n'autorisent qu'une personne (quelqu'un possédant le nom d'utilisateur rbowen) à accéder au répertoire. Dans la plupart des cas, vous devrez autoriser l'accès à plusieurs personnes. C'est ici qu'intervient la directive AuthGroupFile.

Si vous voulez autoriser l'accès à plusieurs personnes, vous devez créer un fichier de groupes qui associe des noms de groupes avec une liste d'utilisateurs de ce groupe. Le format de ce fichier est très simple, et vous pouvez le créer avec votre éditeur favori. Son contenu se présente comme suit :

Nom-de-groupe: rbowen dpitts sungo rshersey

Il s'agit simplement une liste des membres du groupe sous la forme d'une ligne séparée par des espaces.

Pour ajouter un utilisateur à votre fichier de mots de passe préexistant, entrez :

htpasswd /usr/local/apache/passwd/passwords dpitts

Vous obtiendrez le même effet qu'auparavant, mais le mot de passe sera ajouté au fichier, plutôt que d'en créer un nouveau (C'est le drapeau -c qui permet de créer un nouveau fichier de mots de passe)..

Maintenant, vous devez modifier votre fichier .htaccess ou la section <Directory> comme suit :

AuthType Basic
AuthName "By Invitation Only"
# Optional line:
AuthBasicProvider file
AuthUserFile "/usr/local/apache/passwd/passwords"
AuthGroupFile "/usr/local/apache/passwd/groups"
Require group GroupName

Maintenant, quiconque appartient au groupe Nom-de-groupe, et possède une entrée dans le fichier password pourra accéder au répertoire s'il tape le bon mot de passe.

Il existe une autre méthode moins contraignante pour autoriser l'accès à plusieurs personnes. Plutôt que de créer un fichier de groupes, il vous suffit d'ajouter la directive suivante :

Require valid-user

Le remplacement de la ligne Require user rbowen par la ligne Require valid-user autorisera l'accès à quiconque possédant une entrée dans le fichier password, et ayant tapé le bon mot de passe.

Problèmes possibles

L'authentification Basic est spécifiée d'une telle manière que vos nom d'utilisateur et mot de passe doivent être vérifiés chaque fois que vous demandez un document au serveur, et ceci même si vous rechargez la même page, et pour chaque image contenue dans la page (si elles sont situées dans un répertoire protégé). Comme vous pouvez l'imaginer, ceci ralentit un peu le fonctionnement. La mesure dans laquelle le fonctionnement est ralenti est proportionnelle à la taille du fichier des mots de passe, car ce dernier doit être ouvert et la liste des utilisateurs parcourue jusqu'à ce que votre nom soit trouvé, et ceci chaque fois qu'une page est chargée.

En conséquence, ce ralentissement impose une limite pratique au nombre d'utilisateurs que vous pouvez enregistrer dans un fichier de mots de passe. Cette limite va varier en fonction des performances de votre serveur, mais vous commencerez à remarquer un ralentissement lorsque vous atteindrez quelques centaines d'utilisateurs, et serez alors appelés à utiliser une méthode d'authentification différente.

Autre méthode de stockage des mots de passe

Suite au problème évoqué précédemment et induit par le stockage des mots de passe dans un fichier texte, vous pouvez être appelé à stocker vos mots de passe d'une autre manière, par exemple dans une base de données.

Pour y parvenir, on peut utiliser les modules mod_authn_dbm ou mod_authn_dbd. Vous pouvez choisir comme format de stockage dbm ou dbd à la place de file pour la directive AuthBasicProvider.

Par exemple, pour sélectionner un fichier dbm à la place d'un fichier texte :

<Directory "/www/docs/private">

    AuthName "Private"
    AuthType Basic
    AuthBasicProvider dbm
    AuthDBMUserFile "/www/passwords/passwd.dbm"
    Require valid-user

</Directory>

D'autres options sont disponibles. Consultez la documentation de mod_authn_dbm pour plus de détails.

Utilisation de plusieurs fournisseurs d'authentification

Depuis l'arrivée des nouvelles architecture d'autorisation et d'authentification basées sur les fournisseurs, vous n'êtes plus limité à une méthode d'authentification et d'autorisation unique. En fait, on peut panacher autant de fournisseurs que l'on veut, ce qui vous permet d'élaborer l'architecture qui correspond exactement à vos besoins. Dans l'exemple suivant, on utilise conjointement les fournisseurs d'authentification file et LDAP :

<Directory "/www/docs/private">

    AuthName "Private"
    AuthType Basic
    AuthBasicProvider file ldap
    AuthUserFile "/usr/local/apache/passwd/passwords"
    AuthLDAPURL ldap://ldaphost/o=yourorg
    Require valid-user

</Directory>

Dans cet exemple, le fournisseur file va tenter d'authentifier l'utilisateur en premier. S'il n'y parvient pas, le fournisseur LDAP sera sollicité. Ceci permet l'élargissement des possibilités d'authentification si votre organisation implémente plusieurs types de bases d'authentification. D'autres scénarios d'authentification et d'autorisation peuvent associer un type d'authentification avec un autre type d'autorisation. Par exemple, une authentification basée sur un fichier de mots de passe peut permettre l'attribution d'autorisations basée sur un annuaire LDAP.

Tout comme plusieurs fournisseurs d'authentification peuvent être implémentés, on peut aussi utiliser plusieurs méthodes d'autorisation. Dans l'exemple suivant, on utilise à la fois une autorisation à base de fichier de groupes et une autorisation à base de groupes LDAP.

<Directory "/www/docs/private">

    AuthName "Private"
    AuthType Basic
    AuthBasicProvider file
    AuthUserFile "/usr/local/apache/passwd/passwords"
    AuthLDAPURL ldap://ldaphost/o=yourorg
    AuthGroupFile "/usr/local/apache/passwd/groups"
    Require group GroupName
    Require ldap-group cn=mygroup,o=yourorg

</Directory>

Pour un scénario d'autorisation un peu plus avancé, des directives de conteneur d'autorisation comme <RequireAll> et <RequireAny> permettent d'appliquer une logique telle que l'ordre dans lequel les autorisations sont appliquées peut être entièrement contrôlé au niveau de la configuration. Voir Conteneurs d'autorisations pour un exemple de ce contrôle.

Pour aller plus loin qu'une simple autorisation

La manière dont les autorisations sont accordées est désormais beaucoup plus souple qu'une simple vérification auprès d'une seule base de données. Il est maintenant possible de choisir l'ordre, la logique et la manière selon lesquels une autorisation est accordée.

Appliquer logique et ordonnancement

Le contrôle de la manière et de l'ordre selon lesquels le processus d'autorisation était appliqué constituait une sorte de mystère par le passé. Dans Apache 2.2, un mécanisme d'authentification basé sur les fournisseurs a été développé afin de séparer le véritable processus d'authentification de l'autorisation et ses différentes fonctionnalités. Un des avantages colatéraux résidait dans le fait que les fournisseurs d'authentification pouvaient être configurés et appelés selon un ordre particulier indépendant de l'ordre de chargement du module auth proprement dit. Ce mécanisme basé sur les fournisseurs a été étendu au processus d'autorisation. Ceci signifie que la directive Require définit non seulement quelles méthodes d'autorisation doivent être utilisées, mais aussi l'ordre dans lequel elles sont appelées. Les méthodes d'autorisation sont appelées selon l'ordre dans lequel les directives Require apparaissent dans la configuration.

Avec l'introduction des directives de conteneur d'autorisations <RequireAll> et <RequireAny>, la configuration contrôle aussi le moment où les méthodes d'autorisation sont appelées, et quels critères déterminent l'autorisation d'accès. Voir Conteneurs d'autorisations pour un exemple de la manière de les utiliser pour exprimer des logiques d'autorisation complexes.

Par défaut, toutes les directives Require sont traitées comme si elles étaient contenues dans une directive <RequireAny>. En d'autres termes, il suffit qu'une méthode d'autorisation s'applique avec succès pour que l'autorisation soit accordée.

Utilisation de fournisseurs d'autorisation pour le contrôle d'accès

La vérification du nom d'utilisateur et du mot de passe ne constituent qu'un aspect des méthodes d'authentification. Souvent, le contrôle d'accès à certaines personnes n'est pas basé sur leur identité ; il peut dépendre, par exemple de leur provenance.

Les fournisseurs d'autorisation all, env, host et ip vous permettent d'accorder ou refuser l'accès en fonction de critères tels que le nom d'hôte ou l'adresse IP de la machine qui effectue la requête.

L'utilisation de ces fournisseurs est spécifiée à l'aide de la directive Require. Cette directive permet d'enregistrer quels fournisseurs d'autorisation seront appelés dans le processus d'autorisation au cours du traitement de la requête. Par exemple :

Require ip address

où adresse est une adresse IP (ou une adresse IP partielle) ou :

Require host domain_name

où nom_domaine est un nom de domaine entièrement qualifé (ou un nom de domaine partiel) ; vous pouvez indiquer plusieurs adresses ou noms de domaines, si vous le désirez.

Par exemple, si vous voulez rejeter les spams dont une machine vous inonde, vous pouvez utiliser ceci :

<RequireAll>
    Require all granted
    Require not ip 10.252.46.165
</RequireAll>

Ainsi, les visiteurs en provenance de cette adresse ne pourront pas voir le contenu concerné par cette directive. Si, par contre, vous connaissez le nom de la machine, vous pouvez utiliser ceci :

<RequireAll>
    Require all granted
    Require not host host.example.com
</RequireAll>

Et si vous voulez interdire l'accès à toutes les machines d'un domaine, vous pouvez spécifier une partie seulement de l'adresse ou du nom de domaine :

<RequireAll>
    Require all granted
    Require not ip 192.168.205
    Require not host phishers.example.com moreidiots.example
    Require not host ke
</RequireAll>

L'utilisation de la directive <RequireAll> avec de multiples directives <Require>, toutes avec la négation not, n'accordera l'accès que si toutes les conditions négatives sont vérifiées. En d'autres termes, l'accès sera refusé si au moins une des conditions négatives n'est pas vérifiée.

Compatibilité ascendante du contrôle d'accès

L'adoption d'un mécanisme à base de fournisseurs pour l'authentification, a pour effet colatéral de rendre inutiles les directives Order, Allow, Deny et Satisfy. Cependant, et à des fins de compatibilité ascendante vers les anciennes configurations, ces directives ont été déplacées vers le module mod_access_compat.

Note

Les directives fournies par le module mod_access_compat sont devenues obsolètes depuis la refonte du module mod_authz_host. Mélanger d'anciennes directives comme Order, Allow ou Deny avec des nouvelles comme Require est techniquement possible mais déconseillé. En effet, mod_access_compat a été conçu pour supporter des configurations ne contenant que des anciennes directives afin de faciliter le passage à la version 2.4. Voir le document upgrading pour plus de détails.

Mise en cache de l'authentification

Dans certains cas, l'authentification constitue une charge inacceptable pour un fournisseur d'authentification ou votre réseau. Ceci est susceptible d'affecter les utilisateurs du module mod_authn_dbd (ou les fournisseurs tiers/personnalisés). Pour résoudre ce problème, HTTPD 2.3/2.4 propose un nouveau fournisseur de mise en cache, mod_authn_socache, qui permet de mettre en cache les données d'authentification, et ainsi réduire la charge du/des fournisseurs(s) originels.

Cette mise en cache apportera un gain en performance substantiel à certains utilisateurs.

Pour aller plus loin . . .

Vous pouvez aussi lire la documentation de mod_auth_basic et mod_authz_host qui contient des informations supplémentaires à propos du fonctionnement de tout ceci. Certaines configurations d'authentification peuvent aussi être simplifiées à l'aide de la directive <AuthnProviderAlias>.

Les différents algorithmes de chiffrement supportés par Apache pour authentifier les données sont expliqués dans PasswordEncryptions.

Enfin vous pouvez consulter la recette Contrôle d'accès, qui décrit un certain nombre de situations en relation avec le sujet.


Contrôle d'accès - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > How-To / Tutoriels

Contrôle d'accès

Le contrôle d'accès fait référence à tout concept de contrôle d'accès à une ressource quelconque. Il est distinct du processus d'authentification et d'autorisation.

Modules et directives concernés

Plusieurs modules peuvent intervenir dans le contrôle d'accès. Les plus importants sont mod_authz_core et mod_authz_host. Ce document illustre aussi comment utiliser mod_rewrite pour le contrôle d'accès.

Contrôle d'accès en fonction de l'hôte du client

Si vous souhaitez restreindre l'accès à certaines parties de votre site web en fonction de l'addresse de l'hôte de vos visiteurs, le plus simple pour y parvenir consiste à utiliser le module mod_authz_host.

La directive Require permet d'accorder ou d'interdire l'accès à certaines ressources de différentes manières. Ces critères d'accès, en conjonction avec les directives RequireAll, RequireAny, et RequireNone, peuvent être combinés d'une manière suffisamment complexe pour satisfaire votre politique de contrôle d'accès.

Les directives Allow, Deny, et Order fournies par le module mod_access_compat sont obsolètes, et sont appelées à disparaître dans les versions futures. Il est donc déconseillé de les utiliser, et de se fier aux tutoriels qui recommandent leur utilisation.

Les directives Require s'utilisent comme suit :

Require host address
Require ip ip.address

Dans la première forme, nom-hôte est un nom de domaine pleinement qualifié (fqdn), ou un nom de domaine partiel ; vous pouvez spécifier plusieurs noms de domaines, si vous le désirez.

Dans la seconde forme, adresse-ip est une adresse IP complète, une adresse IP partielle, une paire réseau/masque de sous-réseau ou une spécification CIDR de la forme réseau/nnn. Il est possible de spécifier des adresses IPv4 ou IPv6.

Voir la documentation de mod_authz_host pour d'autres exemples de cette syntaxe.

Vous pouvez insérer le mot-clé not pour inverser un critère particulier. Notez que le mot not étant la négation d'une valeur, il ne peut pas être utilisé pour autoriser ou interdire une requête, car non vrai ne sera pas interpreté par httpd comme faux. Ainsi, pour interdire la visite d'une page à l'aide d'une négation, le bloc doit contenir un élément évalué à vrai ou faux. Par exemple, si quelqu'un est en train d'inonder votre forum de messages indésirables, vous pouvez ajouter cette ligne pour lui refuser l'accès :

<RequireAll>
    Require all granted
    Require not ip 10.252.46.165
</RequireAll>

Les visiteurs possédant cette adresse (10.252.46.165) ne pourront pas voir le contenu concerné par cette directive. Si vous voulez interdire l'accès à une machine en fonction de son nom, vous pouvez ajouter ceci :

Require not host host.example.com

Et si vous voulez interdire l'accès à un domaine particulier, vous pouvez spécifier des adresses IP partielles ou des noms de domaine, comme ceci :

Require not ip 192.168.205
Require not host phishers.example.com moreidiots.example
Require not host gov

Les directives RequireAll, RequireAny, et RequireNone permettent également de préciser des critères d'accès plus complexes.

Contrôle d'accès en fonction de variables arbitraires

Vous pouvez accorder ou refuser l'accès en fonction de variables d'environnement arbitraires ou de valeurs d'en-têtes de la requête en utilisant la directive <If>. Par exemple, pour interdire l'accès en fonction du user-agent (le type de navigateur), vous pouvez spécifier ceci :

<If "%{HTTP_USER_AGENT} == 'BadBot'">
    Require all denied
</If>

La syntaxe expr de la directive Require permet de réécrire l'exemple précédent de la manière suivante :

Require expr %{HTTP_USER_AGENT} != 'BadBot'

Avertissement :

Contrôler l'accès en fonction de l'en-tête User-Agent n'est pas une technique fiable, car cet en-tête peut être défini à une valeur quelconque, selon le bon vouloir de l'utilisateur.

Voir le document à propos des expressions pour une description plus approfondie des syntaxes d'expressions et des variables disponibles.

Utilisation de mod_rewrite pour le contrôle d'accès

Le drapeau [F] de la directive RewriteRule permet d'envoyer une réponse de type 403 Forbidden. Il vous permet donc d'interdire l'accès à une ressource en fonction d'un critère arbitraire.

Par exemple, pour bloquer l'accès à une ressources entre 20h et 7h du matin, vous pouvez utiliser mod_rewrite :

RewriteEngine On
RewriteCond "%{TIME_HOUR}" ">=20" [OR]
RewriteCond "%{TIME_HOUR}" "<07"
RewriteRule "^/fridge"     "-" [F]

Toute requête arrivant après 20h ou avant 7h du matin provoquera l'envoi d'une réponse de type 403 Forbidden. Vous pouvez utiliser cette technique pour vérifier toutes sortes de critères. En outre, si vous le préférez, vous pouvez rediriger ou réécrire la requête.

Notez que la directive <If>, introduite à partir de la version 2.4, permet de remplacer le module mod_rewrite dans de nombreuses situations où il était traditionnellement utilisé, et il sera probablement préférable pour vous de tenter de l'utiliser avant de vous tourner vers mod_rewrite.

Informations complémentaires

Le moteur d'expressions vous fournit une grande puissance d'action en fonction de variables du serveur arbitraires, et il vous est conseillé de consulter le document correspondant pour plus de détails.

De même, vous devez lire la documentation du module mod_authz_core pour des exemples de combinaison de critères d'accès multiples, et en particulier la manière dont ces derniers interagissent.

Voir aussi le How-To Authentification and autorisation.


Tutoriel Apache : Contenu dynamique basé sur CGI - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Recettes et tutoriels

Tutoriel Apache : Contenu dynamique basé sur CGI

Introduction

Modules Apparentés Directives Apparentées
  • mod_alias
  • mod_cgi
  • mod_cgid
  • AddHandler
  • Options
  • ScriptAlias

CGI (Common Gateway Interface) définit une méthode d'interaction entre un serveur web et des programmes générateurs de contenu externes, plus souvent appelés programmes CGI ou scripts CGI. Il s'agit d'une méthode simple pour ajouter du contenu dynamique à votre site web en utilisant votre langage de programmation préféré. Ce document est une introduction à la configuration de CGI sur votre serveur web Apache, et une initiation à l'écriture de programmes CGI.

Configurer Apache pour autoriser CGI

Apache doit être configuré pour permettre l'exécution des programmes CGI, pour que vos programmes CGI puissent fonctionner correctement. Il existe plusieurs méthodes pour y parvenir.

Note: si Apache a été compilé avec le support des modules partagés (DSO), vous devez vous assurer que le module CGI est chargé ; vous devez pour cela vérifier que la directive LoadModule correspondante n'a pas été commentée dans votre httpd.conf. Une directive correcte doit ressembler à ceci :
LoadModule cgid_module modules/mod_cgid.so
Sous Windows, ou si l'on utilise un module MPM non-threadé comme prefork, une directive correctement configurée sera du style :
LoadModule cgi_module modules/mod_cgi.so

ScriptAlias

La directive ScriptAlias indique à Apache qu'un répertoire particulier est dédié aux programmes CGI. Apache considérera que tout fichier situé dans ce répertoire est un programme CGI, et tentera de l'exécuter lorsque cette ressource fera l'objet d'une requête client.

La directive ScriptAlias se présente comme suit :

ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"

Cet exemple est tiré de votre fichier de configuration httpd.conf par défaut, si vous avez installé Apache dans son répertoire par défaut. La directive ScriptAlias est similaire à la directive Alias, qui définit à quel répertoire particulier doit correspondre un préfixe d'URL. Alias et ScriptAlias sont généralement utilisés pour accéder à des répertoires situés en dehors du répertoire défini par la directive DocumentRoot. La différence entre Alias et ScriptAlias réside dans le fait que ScriptAlias indique en plus que tout ce qui se trouve sous le préfixe d'URL doit être considéré comme un programme CGI. Ainsi, l'exemple ci-dessus indique à Apache que toute requête pour une ressource commençant par /cgi-bin/ doit être servie depuis le répertoire /usr/local/apache2/cgi-bin/, et doit être traitée en tant que programme CGI.

Par exemple, si une requête pour l'URL http://www.example.com/cgi-bin/test.pl est effectuée, Apache tentera d'exécuter le fichier /usr/local/apache2/cgi-bin/test.pl et en renverra la sortie. Bien entendu, le fichier doit exister, être exécutable, et retourner sa sortie d'une manière particulière, sinon Apache renverra un message d'erreur.

CGI en dehors des répertoires ScripAlias

Pour des raisons de sécurité, la localisation des programmes CGI est souvent restreinte aux répertoires définis par ScriptAlias. De cette manière, les administrateurs peuvent contrôler précisément qui est autorisé à utiliser les programmes CGI. Cependant, si les précautions adéquates quant à la sécurité sont prises, il n'y a aucune raison pour que les programmes CGI ne puissent pas être exécutés depuis d'autres répertoires. Par exemple, vous pouvez autoriser les utilisateurs à enregistrer des contenus web dans leurs répertoires home à l'aide de la directive UserDir. S'ils veulent mettre en oeuvre leurs propres programmes CGI, mais n'ont pas l'autorisation d'accès au répertoire cgi-bin principal, ils devront être en mesure d'exécuter ces programmes depuis un autre répertoire.

L'autorisation d'exécution des programmes CGI dans un répertoire arbitraire se fait en deux étapes. En premier lieu, le gestionnaire cgi-script doit être activé à l'aide d'une directive AddHandler ou SetHandler. En second lieu, ExecCGI doit être spécifié dans la directive Options.

Utilisation d'options explicites pour permettre l'exécution des programmes CGI

Vous pouvez utiliser de manière explicite la directive Options dans le fichier de configuration de votre serveur principal, pour indiquer que l'exécution des programmes CGI est permise depuis un répertoire particulier :

<Directory "/usr/local/apache2/htdocs/somedir">
    Options +ExecCGI
</Directory>

La directive ci-dessus indique à Apache qu'il doit permettre l'exécution des fichiers CGI. Vous devez aussi indiquer au serveur quels fichiers sont des fichiers CGI. La directive AddHandler suivante indique au serveur qu'il doit traiter tous les fichiers possédant une extension cgi ou pl en tant que programmes CGI :

AddHandler cgi-script .cgi .pl

Fichiers .htaccess

Le tutoriel .htaccess montre comment activer les programmes CGI si vous n'avez pas accès au fichier httpd.conf.

Répertoires utilisateurs

Pour permettre l'exécution en tant que programme CGI de tout fichier possédant l'extension .cgi et situé dans un répertoire utilisateur, vous pouvez utiliser la configuration suivante :

<Directory "/home/*/public_html">
    Options +ExecCGI
    AddHandler cgi-script .cgi
</Directory>

Pour indiquer un sous-répertoire cgi-bin d'un répertoire utilisateur où tout fichier sera traité en tant que programme CGI, vous pouvez utiliser ceci :

<Directory "/home/*/public_html/cgi-bin">
    Options ExecCGI
    SetHandler cgi-script
</Directory>

Ecrire un programme CGI

Il y a deux différences principales entre la programmation "standard" et la programmation CGI.

En premier lieu, toute sortie de votre programme CGI doit être précédée d'un en-tête MIME-type. Il s'agit d'un en-tête HTTP qui indique au client quel type de contenu il reçoit. La plupart du temps, il se présente comme suit :

Content-type: text/html

En second lieu, votre sortie doit être en HTML, ou tout autre format qu'un navigateur est en mesure d'afficher. La plupart du temps, il s'agira de HTML, mais occasionnellement, vous pouvez être amené à écrire un programme CGI qui renvoie une image gif, ou un autre type de contenu non-HTML.

A part ces deux différences, un programme CGI ressemblera à tout autre programme que vous pourriez être amené à écrire.

Votre premier programme CGI

L'exemple suivant est un exemple de programme CGI qui permet d'afficher une ligne de caractères dans votre navigateur. Ecrivez ce qui suit, enregistrez le dans un fichier nommé premier.pl, et placez le dans votre répertoire cgi-bin.

#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hello, World.";

Même si Perl ne vous est pas familier, vous devriez être capable de comprendre le fonctionnement de ce programme. La première ligne indique à Apache (ou à toute interface à partir de laquelle le programme s'exécute) que ce programme peut être exécuté en fournissant son fichier à l'interpréteur /usr/bin/perl. La seconde ligne affiche la déclaration du type de contenu considéré, suivie de deux paires "Retour chariot - Nouvelle ligne". Ceci a pour effet d'insérer une ligne vide après l'en-tête pour marquer la fin des en-têtes HTTP, et le début du corps du document. La troisième ligne affiche la chaîne de caractères "Bonjour tout le monde . . .". Et c'est tout ce dont vous avez besoin.

Si vous ouvrez votre navigateur favori et lui indiquez l'adresse

http://www.example.com/cgi-bin/premier.pl

ou toute autre URL correspondant à votre programme CGI, Vous verrez la ligne Bonjour tout le monde . . . s'afficher dans la fenêtre de votre navigateur. Ce n'est pas extraordinaire, mais si vous y êtes parvenu, vous avez de bonnes chances d'y parvenir pour tout autre programme plus sophistiqué.

Mais ça ne marche toujours pas !

Vous devriez voir au moins une des quatre sorties suivantes dans votre navigateur lorsque vous essayez d'accéder à votre programme CGI depuis le web :

Le flux de sortie de votre programme CGI
Impeccable ! Cela signifie que tout fonctionne correctement. Si la sortie est correcte mais n'est pas traitée correctement par le navigateur, assurez-vous d'avoir défini Content-Type de manière appropriée dans votre programme CGI.
Le code source de votre programme CGI ou un message "POST Method Not Allowed"
Cela signifie que vous n'avez pas configuré Apache de manière à ce qu'il puisse traiter votre programme CGI. Relisez la section sur la configuration d'Apache, et essayez de trouver votre erreur.
Un message commençant par "Forbidden"
Ce type de message est révélateur d'un problème de droits. Consultez le journal des erreurs d'Apache et la section ci-dessous sur les droits des fichiers.
Un message contenant "Internal Server Error"
Si vous consultez le journal des erreurs d'Apache, vous y trouverez probablement des messages du type "Premature end of script headers" (Fin prématurée des en-têtes de script), éventuellement accompagnés d'un message d'erreur généré par votre programme CGI. Dans ce cas, il va vous falloir lire chacune des sections ci-dessous pour déterminer ce qui empêche votre programme CGI de générer les en-têtes appropriés.

Droits des fichiers

Souvenez-vous que le serveur ne s'exécute pas sous votre nom. En d'autres termes, lorsque le serveur a démarré, il s'exécute avec les droits d'un utilisateur non privilégié - en général nobody, ou www - et en conséquence, il aura besoin de droits supplémentaires pour pouvoir exécuter des fichiers dont vous êtes le propriétaire. En général, pour qu'un fichier ait des droits suffisants pour être exécutable par nobody, il suffit de lui attribuer des droits d'exécution pour tout le monde :

chmod a+x premier.pl

En outre, si votre programme doit pouvoir accéder en lecture et/ou écriture à d'autres fichiers, ces derniers devront avoir les droits appropriés.

Chemin des exécutables (PATH) et variables d'environnement

Lorsque vous lancez un programme depuis la ligne de commande, certaines informations sont passées au shell sans que vous vous en doutiez. Par exemple, la variable PATH indique au shell où il doit rechercher les exécutables auxquels vous faites référence.

Lorsqu'un programme s'exécute depuis le serveur web en tant que programme CGI, sa variable PATH n'aura peut-être pas la même valeur. Tout programme que vous invoquez dans votre programme CGI ( comme par exemple sendmail) devra être spécifié par son chemin complet, de façon à ce que le shell puisse le trouver lorsqu'il tentera d'exécuter votre programme CGI.

Un exemple typique de spécification de programme est le chemin vers l'interpréteur de script (souvent perl) que l'on trouve à la première ligne de votre programme CGI et qui va ressembler à ceci :

#!/usr/bin/perl

Assurez-vous qu'il s'agit bien du chemin correct vers l'interpréteur.

Lors de l'édition de scripts CGI sous Windows, il se peut que des caractères de fin de ligne soient ajoutés au chemin de l'interpréteur. Assurez-vous donc que les fichiers sont bien transmis au serveur en mode ASCII. Dans le cas contraire, l'OS pourra envoyer des avertissements "Command not found" à cause des caractères de fin de ligne non reconnus car considérés comme faisant partie du nom de fichier de l'interpréteur.

Variables d'environnement manquantes

Si votre programme CGI dépend de variables d'environnement non standards, vous devrez vous assurez que ces variables lui sont bien transmises par Apache.

Lorsque des en-têtes HTTP ne sont pas transmis à l'environnement, assurez-vous qu'ils sont bien formatés selon la RFC 2616, section 4.2 : les noms d'en-têtes doivent commencer par une lettre, elle-même suivie de lettres, chiffres ou traits d'union. Tout en-tête dont le nom viole cette règle sera ignoré.

Erreurs inhérentes au programme

La plupart des échecs dans l'exécution d'un programme CGI proviennent du programme lui-même. Ceci est particulièrement vrai lorsque ce satané programme CGI se bloque, alors que vous avez appris à ne plus commettre les deux erreurs précédentes. La première chose à faire est de vous assurer que votre programme s'exécute depuis la ligne de commande, avant de le tester à partir du serveur web. Par exemple, essayez :

cd /usr/local/apache2/cgi-bin
./premier.pl

(N'invoquez pas l'interpréteur perl. Le shell et Apache doivent être capable de le déterminer à partir de l'information sur le chemin située sur la première ligne du script.)

La première chose que vous devriez voir affichée par votre programme est un ensemble d'en-têtes HTTP, comprenant entre autres le Content-Type, et suivi d'une ligne vide. Si vous voyez quoi que ce soit d'autre, Apache renverra l'erreur Premature end of script headers si vous tentez d'exécuter le programme depuis le serveur. Voir Ecriture d'un programme CGI ci-dessus pour plus de détails.

Journalisation des erreurs

Les journaux d'erreurs sont vos amis. Toute anomalie de fonctionnement est consignée dans le journal des erreurs et c'est ici que vous devez regarder en premier en cas de problème. Si l'hébergeur de votre site ne vous donne pas accès au journal des erreurs, vous avez tout intérêt à vous tourner vers quelqu'un d'autre. Apprenez à déchiffrer les journaux d'erreurs, et vous vous apercevrez que la plupart des problèmes seront rapidement identifiés . . . et résolus.

Suexec

Le programme suexec permet d'exécuter les programmes CGI avec des droits différents selon le serveur virtuel ou le répertoire utilisateur dans lequel ils se situent. Suexec effectue une vérification des droits très stricte, et toute anomalie détectée au cours de cette vérification entraînera un echec d'exécution de votre programme CGI avec affichage de l'erreur Premature end of script headers.

Pour savoir si vous pouvez utiliser suexec, tapez la commande apachectl -V, et regardez le chemin indiqué par SUEXEC_BIN. Si au démarrage d'Apache, ce dernier trouve un exécutable suexec dans ce chemin, suexec sera activé.

Si vous ne maîtrisez pas le fonctionnement de suexec, il vous est déconseillé de l'utiliser. Pour désactiver suexec, supprimer simplement (ou renommez) l'exécutable suexec pointé par SUEXEC_BIN et redémarrez le serveur. Si après une lecture de suexec, vous décidez quand-même de l'utiliser, tapez la commande suexec -V pour voir où se situe le journal de suexec, et utilisez ce dernier pour déterminer quelles règles vous violez éventuellement.

Que se passe-t-il en coulisse

Lorsque vos compétences en programmation CGI seront plus poussées, il s'avérera intéressant pour vous de mieux comprendre ce qui se passe en coulisse, et en particulier la manière dont le navigateur et le serveur dialoguent entre eux. En effet, bien qu'il soit tout à fait louable d'écrire un programme qui affiche "Bonjour tout le monde . . .", cela ne sert pas à grand chose.

Variables d'environnement

Les variables d'environnement sont des valeurs qui gravitent autour de vous lorsque vous utilisez votre ordinateur. Elles sont très utiles, à l'instar de votre chemin par défaut (où votre ordinateur va rechercher le fichier physique correspondant à la commande que vous avez tapée), votre nom d'utilisateur, le type de votre terminal, etc... Pour obtenir une liste complète des variables d'environnement standards que vous utilisez tous les jours, tapez env dans votre interpréteur de commandes.

Au cours de la transaction CGI, le serveur et le navigateur définissent aussi des variables d'environnement, de façon à ce qu'ils puissent communiquer entre eux. Ces variables définissent entre autre le type de navigateur (Netscape, IE, Lynx), le type de serveur (Apache, IIS, WebSite), le nom du programme CGI en cours d'exécution, etc...

Ces variables sont à la disposition du programmeur CGI, et elles constituent 50% de la communication client-serveur. La liste complète des variables requises se trouve à Common Gateway Interface RFC.

Ce programme CGI basique en Perl permet d'afficher toutes les variables d'environnement qui sont échangées. Deux programmes similaires sont fournis avec la distribution d'Apache et situés dans le répertoire cgi-bin. Notez que certaines variables sont obligatoires, alors que d'autres sont optionnelles, si bien que vous verrez s'afficher certaines variables qui ne font pas partie de la liste officielle. De plus, Apache vous propose de nombreuses méthodes pour ajouter vos propres variables d'environnement aux variables de base fournies par défaut.

#!/usr/bin/perl
use strict;
use warnings;

print "Content-type: text/html\n\n";
foreach my $key (keys %ENV) {
    print "$key --> $ENV{$key}<br>";
}

STDIN et STDOUT

L'entrée standard (STDIN) et la sortie standard (STDOUT) constituent d'autres voies de communication entre le client et le serveur. Dans un contexte normal, STDIN correspond au clavier, ou à un fichier fourni au programme à des fins de traitement, et STDOUT à la console ou à l'écran.

Lorsque vous transmettez un formulaire web à un programme CGI par la méthode POST, les données de ce formulaire sont transcrites dans un format spécial et transmises à votre programme CGI via STDIN. Le programme peut alors les traiter comme si elles provenaient du clavier ou d'un fichier.

Ce "format spécial" est très simple. Un nom de champ et sa valeur sont reliés entre eux par un signe "égal" (=), et chacune de ces paires nom champ/valeur est séparée de la suivante par un "et" commercial (&). Les caractères spéciaux comme les espaces, les "et" commerciaux, et les signes "égal" sont convertis en leur équivalent hexadécimal pour éviter qu'ils ne gâchent le travail. La chaîne contenant les données doit ressembler à ceci :

name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey

Vous verrez aussi parfois une chaîne de ce type accolée à une URL. Dans ce cas, le serveur enregistre cette chaîne dans la variable d'environnement appelée QUERY_STRING. On a alors affaire à une requête de type GET. Votre formulaire HTML indique laquelle des méthodes GET ou POST est utilisée pour transmettre les données, en définissant l'attribut METHOD au niveau de la balise FORM.

Votre programme est ensuite chargé d'extraire les informations utiles de cette chaîne. Heureusement, des bibliothèques et des modules sont à votre disposition pour vous aider à traiter ces données, et à gérer les différents aspects de votre programme CGI.

Bibliothèques et modules CGI

Pour écrire un programme CGI, il vous est conseillé d'utiliser une bibliothèque de code, ou un module, qui effectueront une grande partie du travail de base pour vous. Ceci vous permettra de diminuer le nombre d'erreurs et d'accélérer le développement.

Si vous écrivez des programmes CGI en Perl, des modules sont à votre disposition à CPAN. A ce sujet, le module le plus populaire est CGI.pm. Vous pouvez aussi essayer CGI::Lite, qui implémente les fonctionnalités strictement nécessaires, mais suffisantes pour la majorité des programmes.

Si vous écrivez des programmes CGI en C, vous disposez de nombreuses options. L'une d'elles est la bibliothèque CGIC de http://www.boutell.com/cgic/.

Pour plus d'informations

La spécification CGI actuelle est disponible dans la Common Gateway Interface RFC.

Lorsque vous postez une question à propos d'un problème CGI que vous rencontrez, que ce soit dans une liste de diffusion ou dans un newsgroup, faites en sorte de fournir suffisamment d'informations sur le problème rencontré, ce que vous attendiez exactement, et en quoi ce qui se produit est réellement différent de ce que vous attendiez, quel serveur vous utilisez, en quel langage votre programme CGI a été écrit, et, si possible, son code source. Ceci permettra une résolution plus aisée de votre problème.

Notez que les questions à propos de problèmes CGI ne doivent jamais être postées dans la base de données de bogues d'Apache, à moins que vous ne soyez sûr d'avoir trouvé un problème dans le code source d'Apache.


Tutoriel Apache httpd : Introduction aux "Inclusions Côté Serveur" (Server Side Includes - SSI) - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Recettes et tutoriels

Tutoriel Apache httpd : Introduction aux "Inclusions Côté Serveur" (Server Side Includes - SSI)

Les SSI permettent d'ajouter du contenu dynamique à des documents HTML préexistants.

Introduction

Modules Apparentés Directives Apparentées
  • mod_include
  • mod_cgi
  • mod_expires
  • Options
  • XBitHack
  • AddType
  • SetOutputFilter
  • BrowserMatchNoCase

Cet article traite des Inclusions Côté Serveur (Server Side Includes), plus communément appelés SSI. Vous trouverez ici la manière de configurer votre serveur pour permettre les SSI, ainsi qu'une introduction à quelques techniques SSI de base permettant d'ajouter du contenu dynamique à vos pages HTML préexistantes.

La dernière partie de cet article sera consacrée aux configurations SSI plus avancées, telles que les expressions conditionnelles dans les directives SSI.

Qu'est-ce que SSI ?

SSI (Server Side Includes) est constitué de directives placées dans des pages HTML, et évaluées par le serveur au moment où les pages sont servies. Elles vous permettent d'ajouter du contenu généré dynamiquement à une page HTML préexistante, sans avoir à servir la page entière via un programme CGI, ou toute autre technologie de contenu dynamique.

Par exemple, vous pouvez insérer la directive suivante dans une page HTML existante :

<!--#echo var="DATE_LOCAL" -->

Ainsi, lorsque la page sera servie, la directive sera évaluée et remplacée par sa valeur :

Tuesday, 15-Jan-2013 19:28:54 EST

Le choix entre l'utilisation des SSI et la génération entière de la page par un programme quelconque, est en général dicté par la proportion de contenu statique et de contenu devant être généré chaque fois que la page est servie. SSI est idéal pour ajouter de petites quantités d'information, comme l'heure courante dans l'exemple précédent. Mais si la plus grande partie de votre page est générée au moment où elle est servie, vous devez vous tourner vers une autre solution.

Configurer votre serveur pour permettre les SSI

Pour permettre l'utilisation des SSI sur votre serveur, vous devez ajouter la directive suivante dans votre fichier httpd.conf, ou dans un fichier .htaccess :

Options +Includes

Cette directive indique à Apache que vous désirez permettre la recherche de directives SSI lors de l'interprétation des fichiers. Notez cependant que la plupart des configurations contiennent de nombreuses directives Options qui peuvent s'écraser les unes les autres. Vous devrez probablement appliquer ces directives Options au répertoire spécifique pour lequel vous voulez activer les SSI, afin d'être sûr qu'elles y seront bien activées.

Tout fichier ne fera cependant pas l'objet de recherche de directives SSI. Vous devez indiquer à Apache quels fichiers seront concernés. Vous pouvez y parvenir en indiquant une extension, comme .shtml, à l'aide des directives suivantes :

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

Un des désavantages de cette approche réside dans le fait que si vous voulez ajouter des directives SSI à une page préexistante, vous devrez changer le nom de cette page, et donc tout lien qui la contient, de façon à ce qu'elle possède l'extension .shtml, condition nécessaire pour que les directives SSI qu'elle contient soient traitées.

Une autre méthode consiste à utiliser la directive XBitHack :

XBitHack on

La directive XBitHack indique à Apache qu'il doit rechercher des directivves SSI dans les fichiers si leur bit d'exécution est positionné. Il n'est ainsi plus nécessaire de changer le nom du fichier pour ajouter des directives SSI à une page préexistante ; vous devez simplement attribuer les droits d'exécution au fichier à l'aide de chmod.

chmod +x pagename.html

Un bref commentaire sur ce qu'il ne faut pas faire. Certaines personnes peuvent vous conseiller de tout simplement indiquer à Apache de rechercher des directives SSI dans tous les fichiers .html, ce qui vous évite d'avoir à gérer les noms de fichiers avec extension .shtml. Ils n'ont probablement pas entendu parler de la directive XBitHack. En effet, vous devez garder à l'esprit qu'en faisant ceci, Apache va devoir rechercher des directives SSI dans chaque fichier qu'il sert, même s'il n'en contient aucune. Ce n'est donc pas une bonne idée car les performances peuvent en être sensiblement affectées.

Bien entendu, sous Windows, il n'y a pas de bit d'exécution à positionner, ce qui limite un peu vos choix.

Dans sa configuration par défaut, Apache n'envoie pas la date de dernière modification ou les en-têtes HTTP relatifs à la taille des contenus dans les pages SSI, car ses valeurs sont difficiles à calculer pour les contenus dynamiques. Ceci peut induire une impression de diminution des performances côté client, en empêchant la mise en cache de votre document. Il existe deux méthodes pour résoudre ce problème :

  1. Utilisez la configuration XBitHack Full. Elle indique à Apache de déterminer la date de dernière modification en ne regardant que la date du fichier à l'origine de la requête, tout en ignorant la date de modification de tout fichier inclus.
  2. Utilisez les directives fournies par le module mod_expires pour définir de manière explicite la date d'expiration de vos fichiers, laissant par la-même aux navigateurs et aux mandataires le soin de déterminer s'il est opportun ou non de les mettre en cache.

Directives SSI de base

Les directives SSI adoptent la syntaxe suivante :

<!--#fonction attribut=valeur attribut=valeur ... -->

Le format d'une directive SSI étant similaire à celui d'un commentaire HTML, si vous n'avez pas activé correctement SSI, le navigateur l'ignorera, mais elle sera encore visible dans le source HTML. Si SSI est correctement configuré, la directive sera remplacée par ses résultats.

"fonction" peut prendre de nombreuses formes, et nous décrirons plus précisément la plupart d'entre eux dans la prochaine version de ce document. Pour le moment, voici quelques exemples de ce que vous pouvez faire avec SSI.

La date courante

<!--#echo var="DATE_LOCAL" -->

La fonction echo permet d'afficher la valeur d'une variable. Il existe un grand nombre de variables standards, y compris l'ensemble des variables d'environnement disponibles pour les programmes CGI. De plus, vous pouvez définir vos propres variables à l'aide de la fonction set.

Si vous n'aimez pas le format sous lequel la date s'affiche, vous pouvez utiliser la fonction config avec un attribut timefmt, pour le modifier.

<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var="DATE_LOCAL" -->

Date de modification du fichier

Dernière modification du document <!--#flastmod file="index.html" -->

Le format peut là aussi être modifié à l'aide de l'attribut timefmt.

Inclusion des résultats d'un programme CGI

C'est le cas le plus courant d'utilisation des SSI - afficher les résultats d'un programme CGI, comme l'universellement adoré "compteur d'accès".

<!--#include virtual="/cgi-bin/counter.pl" -->

Exemples additionnels

Vous trouverez dans ce qui suit quelques exemples spécifiques de ce que vous pouvez faire de vos documents HTML avec SSI.

Quand ce document a-t-il été modifié ?

Nous avons mentionné plus haut que vous pouviez utiliser SSI pour informer l'utilisateur de la date de dernière modification du document. Cependant, la méthode pour y parvenir n'a pas été vraiment abordée. Placé dans votre document HTML, le code suivant va insérer un repère de temps dans votre page. Bien entendu, SSI devra avoir été correctement activé, comme décrit plus haut.

<!--#config timefmt="%A %B %d, %Y" -->
Dernière modification du fichier <!--#flastmod file="ssi.shtml" -->

Bien entendu, vous devez remplacer ssi.shtml par le nom du fichier auquel vous faites référence. Ceci ne conviendra pas si vous recherchez un morceau de code générique que vous pourrez insérer dans tout fichier ; dans ce cas, il est préférable d'utiliser la variable LAST_MODIFIED :

<!--#config timefmt="%D" -->
This file last modified <!--#echo var="LAST_MODIFIED" -->

Pour plus de détails sur le format timefmt, tapez strftime dans votre moteur de recherche préferé. La syntaxe est identique.

Inclusion d'un pied de page standard

Si le site que vous gérez comporte plus que quelques pages, vous allez vite vous apercevoir qu'effectuer des modifications sur toutes ces pages peut devenir très contraignant, en particulier si vous voulez qu'elles conservent un aspect homogène.

Inclure un fichier pour un en-tête et/ou un pied de page peut simplifier cette corvée de mises à jour. Il vous suffit de confectionner un fichier de pied de page, et de l'inclure dans chaque page à l'aide de l'élément SSI include. Pour définir le fichier à inclure, la fonction include peut utiliser soit l'attribut file, soit l'attribut virtual. L'attribut file est un chemin de fichier relatif au répertoire courant. C'est à dire qu'il ne peut ni avoir pour valeur un chemin absolu (commençant par /), ni comporter "../" dans son chemin. L'attribut virtual est probablement plus commode, et peut spécifier une URL relative au document servi. Elle peut commencer par un /, mais le fichier inclus et le fichier servi doivent résider sur le même serveur.

<!--#include virtual="/footer.html" -->

Je combinerai souvent ces deux derniers points, en ajoutant une directive LAST_MODIFIED dans un fichier de pied de page destiné à être inclus. Le fichier inclus peut contenir des directives SSI, et les inclusions peuvent être imbriquées - à savoir, le fichier inclus peut inclure un autre fichier, etc...

Que puis-je configurer d'autre ?

En plus du format de date, vous pouvez utiliser l'élément config pour configurer deux autres choses.

En général, lorsque quelque chose se passe mal avec votre directive SSI, vous recevez le message :

[an error occurred while processing this directive]

Pour modifier ce message, vous pouvez utiliser l'attribut errmsg avec la fonction config :

<!--#config errmsg="[Il semblerait que vous ne sachiez pas utiliser les SSI]" -->

Il est cependant probable que les utilisateurs finaux ne voient jamais ce message, car vous aurez résolu tous les problèmes issus de vos directives SSI avant que votre site ne soit mis en production. (N'est-ce pas ?)

Vous pouvez aussi modifier le format sous lequel les tailles de fichiers sont affichées à l'aide de l'attribut sizefmt. Vous pouvez spécifier bytes pour un affichage en octets, ou abbrev pour un affichage plus concis en Ko ou Mo, selon le cas.

Exécution de commandes

Voici autre chose que vous pouvez faire avec la fonction exec. Vous pouvez vraiment faire exécuter une commande par SSI en utilisant le shell (/bin/sh, pour être plus précis - ou le shell DOS, si vous êtes sous Win32). Par exemple, ce qui suit vous permet d'afficher le contenu d'un répertoire.

<pre>
<!--#exec cmd="ls" -->
</pre>

ou, sous Windows

<pre>
<!--#exec cmd="dir" -->
</pre>

Vous noterez probablement l'étrange formatage provoqué par cette directive sous Windows, car la sortie de dir contient la chaîne de caractères "<dir>", ce qui trompe le navigateur.

Notez que cette fonctionnalité est très dangereuse, car elle va permettre d'exécuter tout code associé à l'élément exec. Si vous êtes dans la situation où les utilisateurs peuvent éditer le contenu de vos pages web, dans le cas d'un "livre d'or" par exemple, assurez-vous de désactiver cette fonctionnalité. Vous pouvez, tout en permettant les SSI, désactiver la fonctionnalité exec à l'aide de l'argument IncludesNOEXEC de la directive Options.

Techniques SSI avancées

Outre l'affichage de contenu, les SSI d'Apache vous permettent de définir des variables, et de les utiliser dans des comparaisons et des conditions.

Définition de variables

Avec l'élément set, vous pouvez définir des variables pour un usage ultérieur. Comme nous en aurons besoin plus loin, nous allons en parler tout de suite. La syntaxe se présente comme suit :

<!--#set var="name" value="Rich" -->

Pour affecter une valeur à vos variables, en plus de la définition littérale de l'exemple ci-dessus, vous pouvez utiliser une autre variable, y compris les variables d'environnement, ou les variables décrites plus haut (comme LAST_MODIFIED par exemple). Pour indiquer qu'il s'agit d'une variable et non d'une chaîne, vous devez utiliser le symbole dollar ($) devant le nom de la variable.

<!--#set var="modified" value="$LAST_MODIFIED" -->

Pour insérer un caractère $ dans la valeur de votre variable, vous devez l'échapper à l'aide d'un backslash.

<!--#set var="cost" value="\$100" -->

Enfin, si vous voulez insérer une variable dans une chaîne, et s'il y a une chance pour que le nom de la variable se confonde avec le reste de la chaîne, vous pouvez l'entourer d'accolades pour eviter toute confusion (Il est difficile de trouver un bon exemple pour illustrer ceci, mais j'espère que vous comprendrez).

<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->

Expressions conditionnelles

Maintenent que nous avons des variables, et que nous pouvons définir et comparer leurs valeurs, nous sommes à même de les utiliser dans des expressions conditionnelles. Ceci confère à SSI le statut de petit langage de programmation. mod_include fournit une structure if, elif, else, endif pour la construction d'expressions conditionnelles, ce qui vous permet de générer plusieurs pages logiques à partir d'une seule vraie page.

La structure de l'expression conditionnelle est :

<!--#if expr="condition" -->
<!--#elif expr="condition" -->
<!--#else -->
<!--#endif -->

Une condition peut revêtir la forme de toute comparaison logique - soit une comparaison de valeurs avec une autre, soit une vérification de la "vérité" d'une valeur particulière (Une chaîne donnée est vraie si elle n'est pas vide). Pour une liste exhaustive des opérateurs de comparaison disponibles, voir la documentation du module mod_include.

Par exemple, spour insérer l'heure du jour dans votre page web, vous pouvez ajouter ces lignes dans la page HTML :

Good <!--#if expr="%{TIME_HOUR} <12" -->
morning!
<!--#else -->
afternoon!
<!--#endif -->

Toute autre variable (que vous avez définie, ou une variable d'environnement normale) peut être utilisée dans les expressions conditionnelles. Voir le document Expressions rationnelles dans le serveur HTTP Apache pour plus de détails à propos du fonctionnement du moteur d'évaluation des expressions rationnelles.

Associée à la possibilité avec Apache de définir des variables d'environnement à l'aide de directives SetEnvIf, ainsi que d'autres directives en rapport, cette fonctionnalité vous permet d'ajouter une grande variété de contenus dynamiques côté serveur sans avoir à concevoir une application web de A à Z.

Conclusion

SSI ne remplace certainement pas CGI, ou d'autres technologies utilisées pour la génération de pages web dynamiques. Mais c'est une bonne méthode pour ajouter des petits contenus dynamiques à vos pages, sans devoir fournir un gros effort supplémentaire.


Tutoriel du serveur HTTP Apache : fichiers .htaccess - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Recettes / Tutoriels

Tutoriel du serveur HTTP Apache : fichiers .htaccess

Les fichiers .htaccess fournissent une méthode pour modifier la configuration du serveur au niveau de chaque répertoire.

Fichiers .htaccess

Modules Apparentés Directives Apparentées
  • core
  • mod_authn_file
  • mod_authz_groupfile
  • mod_cgi
  • mod_include
  • mod_mime
  • AccessFileName
  • AllowOverride
  • Options
  • AddHandler
  • SetHandler
  • AuthType
  • AuthName
  • AuthUserFile
  • AuthGroupFile
  • Require
Les fichiers .htaccess ne doivent être utilisés que si vous n'avez pas accès au fichier de configuration du serveur principal. L'utilisation des fichiers .htaccess ralentit le fonctionnement de votre serveur HTTP Apache. Il est toujours préférable de définir les directives que vous pouvez inclure dans un fichier .htaccess dans une section Directory, car elles produiront le même effet avec de meilleures performances.

Que sont ce fichiers, comment les utiliser ?

Les fichiers .htaccess (ou "fichiers de configuration distribués") fournissent une méthode pour modifier la configuration du serveur au niveau d'un répertoire. Un fichier, contenant une ou plusieurs directives de configuration, est placé dans un répertoire de documents particulier, et ses directives s'appliquent à ce répertoire et à tous ses sous-répertoires.

Note :

Si vous voulez donner un autre nom à votre fichier .htaccess, vous pouvez le faire en utilisant la directive AccessFileName. Par exemple, si vous préférez nommer votre fichier .config, vous pouvez mettre ceci dans le fichier de configuration de votre serveur :

AccessFileName ".config"

En général, les fichiers .htaccess utilisent la même syntaxe que les fichiers de configuration principaux. Ce que vous pouvez mettre dans ces fichier est déterminé par la directive AllowOverride. Cette directive spécifie, sous forme de catégories, quelles directives seront traitées si elles se trouvent dans un fichier .htaccess. Si une directive est permise dans un fichier .htaccess file, la documentation de cette directive contiendra une section Override, spécifiant quelle valeur doit prendre AllowOverride pour que cette directive soit traitée.

Par exemple, si vous regardez la documentation de la directive AddDefaultCharset, vous verrez que cette dernière est permise dans les fichiers .htaccess (Voir la ligne de contexte dans le résumé de la directive). La ligne Override indique FileInfo. Vous devez donc avoir au moins AllowOverride FileInfo pour que cette directive soit traitée dans les fichiers .htaccess.

Exemple :

Contexte : | configuration du serveur, serveur virtuel, directory, .htaccess
Override: | FileInfo

Si vous n'êtes pas sûr qu'une directive particulière soit permise dans un fichier .htaccess, lisez la documentation de cette directive, et consultez la ligne de contexte pour ".htaccess".

Quand doit-on (ne doit-on pas) utiliser les fichiers .htaccess ?

En principe, vous ne devriez utiliser les fichiers .htaccess que lorsque vous n'avez pas accès au fichier de configuration du serveur principal. Par exemple, la fausse idée selon laquelle l'authentification de l'utilisateur devrait toujours être faite dans les fichiers .htaccess est très répandue. Il est aussi souvent avancé, ces dernières années, que les directives de mod_rewrite doivent être définies dans les fichiers .htaccess. Ceci est tout simplement faux. Vous pouvez configurer l'authentification des utilisateurs au niveau de la configuration du serveur principal, et c'est en fait cette méthode qui doit être privilégiée. De même, les directives de mod_rewrite fonctionneront mieux, à de nombreux égards, dans le contexte du serveur principal.

Les fichiers .htaccess ne devraient être utilisés que dans le cas où les fournisseurs de contenu ont besoin de modifier la configuration du serveur au niveau d'un répertoire, mais ne possèdent pas l'accès root sur le système du serveur. Si l'administrateur du serveur ne souhaite pas effectuer des modifications de configuration incessantes, il peut être intéressant de permettre aux utilisateurs isolés d'effectuer eux-mêmes ces modifications par le biais de fichiers .htaccess. Ceci est particulièrement vrai dans le cas où le fournisseur d'accès à Internet héberge de nombreux sites d'utilisateurs sur un seul serveur, et souhaite que ces utilisateurs puissent modifier eux-mêmes leurs configurations.

Cependant et d'une manière générale, il vaut mieux éviter d'utiliser les fichiers .htaccess. Tout élément de configuration que vous pourriez vouloir mettre dans un fichier .htaccess, peut aussi être mis, et avec la même efficacité, dans une section <Directory> du fichier de configuration de votre serveur principal.

Il y a deux raisons principales d'éviter l'utilisation des fichiers .htaccess.

La première est liée aux performances. Lorsque la directive AllowOverride est définie de façon à autoriser l'utilisation des fichiers .htaccess, httpd va rechercher leur présence dans chaque répertoire. Ainsi, permettre l'utilisation des fichiers .htaccess est déjà en soi une cause de dégradation des performances, que vous utilisiez effectivement ces fichiers ou non ! De plus, le fichier .htaccess est chargé en mémoire chaque fois qu'un document fait l'objet d'une requête.

Notez aussi que httpd doit rechercher les fichiers .htaccess dans tous les répertoires de niveau supérieur, afin de rassembler toutes les directives qui s'appliquent au répertoire courant (Voir la section comment sont appliquées les directives). Ainsi, si un fichier fait l'objet d'une requête à partir d'un répertoire /www/htdocs/exemple, httpd doit rechercher les fichiers suivants :

/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/exemple/.htaccess

En conséquence, chaque accès à un fichier de ce répertoire nécessite 4 accès au système de fichiers supplémentaires pour rechercher des fichiers .htaccess, même si aucun de ces fichiers n'est présent. Notez que cet exemple ne peut se produire que si les fichiers .htaccess ont été autorisés pour le répertoire /, ce qui est rarement le cas.

La seconde raison d'éviter l'utilisation des fichiers .htaccess est liée à la sécurité. Si vous permettez aux utilisateurs de modifier la configuration du serveur, il peut en résulter des conséquences sur lesquelles vous n'aurez aucun contrôle. Réfléchissez bien avant de donner ce privilège à vos utilisateurs. Notez aussi que ne pas donner aux utilisateurs les privilèges dont ils ont besoin va entraîner une augmentation des demandes de support technique. Assurez-vous d'avoir informé clairement vos utilisateurs du niveau de privilèges que vous leur avez attribué. Indiquer exactement comment vous avez défini la directive AllowOverride et diriger les utilisateurs vers la documentation correspondante vous évitera bien des confusions ultérieures.

Notez que mettre un fichier .htaccess contenant une directive dans un répertoire /www/htdocs/exemple revient exactement au même que mettre la même directive dans une section Directory <Directory "/www/htdocs/exemple"> du fichier de configuration de votre serveur principal :

Fichier .htaccess dans /www/htdocs/exemple :

Contenu du fichier .htaccess dans /www/htdocs/exemple

AddType text/example ".exm"

Section de votre fichier httpd.conf

<Directory "/www/htdocs/example">
    AddType text/example .exm
</Directory>

Cependant, la perte de performances sera moindre si vous définissez cette directive dans la configuration de votre serveur principal, car cette dernière ne sera chargée qu'une seule fois au moment du démarrage du serveur, alors qu'elle le sera à chaque accès dans le cas d'un fichier .htaccess.

L'utilisation des fichiers .htaccess peut être entièrement désactivée en définissant la directive AllowOverride à none :

AllowOverride None

Comment sont appliquées les directives ?

Les directives de configuration situées dans un fichier .htaccess s'appliquent au répertoire dans lequel ce fichier .htaccess se trouve, ainsi qu'à tous ses sous-répertoires. Cependant, il est important de garder à l'esprit qu'il peut y avoir des fichiers .htaccess dans les répertoires de niveau supérieur. Les directives sont appliquées selon l'ordre dans lequel elles sont rencontrées. Ainsi, les directives d'un fichier .htaccess situé dans un répertoire particulier peuvent écraser les directives se trouvant dans des fichiers .htaccess situés à un niveau supérieur dans l'arborescence des répertoires. Et ces dernières peuvent elles-mêmes avoir écrasé des directives d'un fichier .htaccess situé à un niveau encore plus haut, ou dans le fichier de configuration du serveur principal.

Exemple :

Dans le répertoire /www/htdocs/exemple1 se trouve un fichier .htaccess contenant ce qui suit :

Options +ExecCGI

Note : "AllowOverride Options" doit être présent pour permettre l'utilisation de la directive "Options" dans les fichiers .htaccess.

Dans le répertoire /www/htdocs/exemple1/exemple2 se trouve un fichier .htaccess contenant ce qui suit :

Options Includes

Ainsi, à cause de ce second fichier .htaccess du répertoire /www/htdocs/exemple1/exemple2, l'exécution des CGI est interdite, car la dernière définition d'options Options Includes écrase toute autre définition d'options d'un fichier .htaccess situé dans un répertoire de niveau supérieur.

Interactions entre les fichiers .htaccess et les fichiers de configuration du serveur principal

Comme indiqué dans la documentation sur les Sections de configuration, les fichiers .htaccess peuvent écraser les directives des sections <Directory> pour le répertoire correspondant, mais peuvent eux-mêmes être écrasés par d'autres types de sections des fichiers de la configuration principale. Cette possibilité peut s'avérer utile pour forcer certaines configurations, même en cas de présence de l'option libérale AllowOverride. Par exemple, pour interdire l'exécution de scripts en autorisant la définition de toute autre option dans les fichiers .htaccess, vous pouvez utiliser :

<Directory "/www/htdocs">
    AllowOverride All
</Directory>

<Location "/">
    Options +IncludesNoExec -ExecCGI
</Location>
Dans cet exemple, on considère que le chemin défini par la directive DocumentRoot est /www/htdocs.

Exemple d'authentification

Si vous accédez directement à ce point du document pour apprendre à effectuer une authentification, il est important de noter ceci. Il existe une fausse idée selon laquelle il serait nécessaire d'utiliser les fichiers .htaccess pour implémenter l'authentification par mot de passe. Ceci est tout simplement faux. Pour y parvenir, il est préférable de mettre les directives d'authentification dans une section <Directory> du fichier de configuration de votre serveur principal, et les fichiers .htaccess ne devraient être utilisés que dans le cas où vous n'avez pas accès au fichier de configuration du serveur principal. Voir ci-dessus pour savoir dans quels cas vous devez ou ne devez pas utiliser les fichiers .htaccess.

Ceci étant dit, si vous pensez que vous devez quand-même utiliser un fichier .htaccess, vous pouvez utiliser la configuration suivante :

Contenu du fichier .htaccess :

AuthType Basic
AuthName "Password Required"
AuthUserFile "/www/passwords/password.file"
AuthGroupFile "/www/passwords/group.file"
Require group admins

Notez que AllowOverride AuthConfig doit être présent pour que ces directives produisent leur effet.

Vous pouvez vous référer au tutoriel sur l'authentification pour une description plus détaillée de l'authentification et de l'autorisation.

Exemple d'Inclusion Côté Serveur (Server Side Includes - SSI)

Les fichiers .htaccess sont aussi couramment utilisés pour activer les SSI pour un répertoire particulier. Pour y parvenir, on utilise les directives de configuration suivantes, placées dans un fichier .htaccess enregistré dans le répertoire considéré :

Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml

Notez que AllowOverride Options et AllowOverride FileInfo doivent être tous les deux présents pour que ces directives puissent produire leur effet.

Vous pouvez vous référer au tutoriel SSI pour une description plus détaillée des SSI.

Les règles de réécriture dans les fichiers .htaccess

Sivous utilisez des directives RewriteRule dans un fichier .htaccess, gardez à l'esprit que les choses sont légèrement différentes dans un contexte de répertoire. En particulier, les règles sont relatives au répertoire courant, et non à l'URI original. Considérez les exemples suivants :

# Dans httpd.conf
RewriteRule "^/images/(.+)\.jpg" "/images/$1.png"

# Dans un fichier .htaccess situé dans le répertoire racine de vos
# documents
RewriteRule "^images/(.+)\.jpg" "images/$1.png"

# Dans un fichier .htaccess situé dans le répertoire images/
RewriteRule "^(.+)\.jpg" "$1.png"

On voit que si le fichier .htaccess se situe à la racine de vos documents, le slash de tête est supprimé de la valeur de remplacement spécifiée pour la règle RewriteRule, et que si le fichier .htaccess se situe dans le répertoire images, la chaîne /images/ disparaît de cette même valeur de remplacement. Il doit donc en être de même dans votre expression rationnelle.

Veuillez vous référer à cette documentation pour une étude détaillée de l'utilisation du module mod_rewrite.

Exemple de CGI

En fin de compte, vous avez décidé d'utiliser un fichier .htaccess pour permettre l'exécution des programmes CGI dans un répertoire particulier. Pour y parvenir, vous pouvez utiliser la configuration suivante :

Options +ExecCGI
AddHandler cgi-script cgi pl

Alternativement, si vous souhaitez que tous les fichiers d'un répertoire donné soient considérés comme des programmes CGI, vous pouvez utiliser la configuration suivante :

Options +ExecCGI
SetHandler cgi-script

Notez que AllowOverride Options et AllowOverride FileInfo doivent être tous les deux présents pour que ces directives puissent produire leur effet.

Vous pouvez vous référer au tutoriel CGI pour une description plus détaillée de la configuration et de la proprammation CGI.

Résolution des problèmes

De nombreuses raisons peuvent être à l'origine du fait que les directives que vous avez mises dans un fichier .htaccess ne produisent pas l'effet désiré.

Le plus souvent, le problème vient du fait que la définition de la directive AllowOverride ne permet pas l'activation des directives de votre fichier .htaccess. Vérifiez si une directive AllowOverride None n'affecte pas le répertoire où se trouve votre fichier. Un bon test consiste à mettre des directives dont la syntaxe est erronée dans votre ficher .htaccess et de recharger la page. Si aucune erreur n'est générée par le serveur, il est pratiquement certain qu'une directive AllowOverride None affecte votre répertoire.

Par contre, si vous obtenez des erreurs de serveur lorsque vous tentez d'accéder à des documents, consultez votre journal des erreurs de httpd. Il vous indiquera probablement que la directive utilisée dans votre fichier .htaccess n'est pas permise.

[Fri Sep 17 18:43:16 2010] [alert] [client 192.168.200.51] /var/www/html/.htaccess: DirectoryIndex not allowed here

Cela signifie soit que vous utilisez une directive qui n'est jamais permise dans les fichiers .htaccess, soit que vous n'avez tout simplement pas défini la directive AllowOverride à un niveau suffisant pour la directive que vous utilisez. Consultez la documentation de cette directive pour déterminer quel cas s'applique.

Le journal des erreurs peut aussi vous signaler une erreur de syntaxe dans l'usage de la directive elle-même.

[Sat Aug 09 16:22:34 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteCond: bad flag delimiters

Dans ce cas, le message d'erreur sera spécifique à l'erreur de syntaxe que vous avez commise.


Répertoires web utilisateurs - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Recettes et tutoriels

Répertoires web utilisateurs

Sur les systèmes multi-utilisateurs, on peut permettre à chaque utilisateur d'avoir un site web dans son répertoire home à l'aide de la directive UserDir. Les visiteurs de l'URL http://example.com/~nom_utilisateur/ recevront un contenu situé dans le répertoire home de l'utilisateur "nom_utilisateur", et dans le sous-répertoire spécifié par la directive UserDir.

Notez que par défaut, l'accès à ces répertoires n'est pas permis. Vous pouvez en permettre l'accès à l'aide de la directive UserDir en décommentant la ligne :

#Include conf/extra/httpd-userdir.conf

dans le fichier de configuration par défaut conf/httpd.conf, et en adaptant le fichier httpd-userdir.conf selon vos besoins, ou en incluant les directives appropriées dans une section <Directory> du fichier de configuration principal.

Voir aussi

  • Mise en correspondance des URLs avec le système de fichiers

Répertoires web utilisateurs

Modules Apparentés Directives Apparentées
  • mod_userdir
  • UserDir
  • DirectoryMatch
  • AllowOverride

Définition du chemin des fichiers avec UserDir

La directive UserDir permet de spécifier un répertoire à partir duquel le contenu de l'utilisateur pourra être chargé. Elle peut revêtir plusieurs formes.

Si le chemin spécifié ne commence pas par un slash, il sera interprété comme chemin relatif au répertoire home de l'utilisateur considéré. Par exemple, avec cette configuration :

UserDir public_html

l'URL http://example.com/~rbowen/fichier.html correspondra au chemin fichier /home/rbowen/public_html/fichier.html

Si le chemin spécifié commence par un slash, le chemin du fichier sera construit en utilisant ce chemin, suivi du nom de l'utilisateur considéré. Par exemple, avec cette configuration :

UserDir /var/html

l'URL http://example.com/~rbowen/fichier.html correspondra au chemin fichier /var/html/rbowen/fichier.html

Si le chemin spécifié contient un astérisque (*), ce dernier sera remplacé par le nom de l'utilisateur dans le chemin du fichier correspondant. Par exemple, avec cette configuration :

UserDir /var/www/*/docs

l'URL http://example.com/~rbowen/fichier.html correspondra au chemin fichier /var/www/rbowen/docs/fichier.html

On peut aussi définir plusieurs répertoires ou chemins de répertoires.

UserDir public_html /var/html

Avec l'URL http://example.com/~rbowen/fichier.html, Apache va rechercher ~rbowen. S'il ne le trouve pas, Apache va rechercher rbowen dans /var/html. S'il le trouve, l'URL ci-dessus correspondra au chemin fichier /var/html/rbowen/file.html

Redirection vers des URLs externes

On peut utiliser la directive UserDir pour rediriger les requêtes relatives aux répertoires utilisateurs vers des URLs externes.

UserDir http://example.org/users/*/

L'exemple ci-dessus va rediriger une requête pour http://example.com/~bob/abc.html vers http://exemple.org/users/bob/abc.html.

Définition de la liste des utilisateurs autorisés à utiliser cette fonctionnalité

En suivant la syntaxe décrite dans la documentation de UserDir, vous pouvez définir quels utilisateurs sont autorisés à utiliser cette fonctionnalité :

UserDir disabled root jro fish

La configuration ci-dessus va autoriser l'utilisation de la fonctionnalité pour tous les utilisateurs, à l'exception de ceux listés à la suite de l'argument disabled. De même, vous pouvez interdire l'utilisation de la fonctionnalité à tous les utilisateurs sauf certains d'entre eux en utilisant une configuration du style :

UserDir disabled
UserDir enabled rbowen krietz

Vous trouverez d'autres exemples dans la documentation de UserDir.

Définition d'un répertoire CGI pour chaque utilisateur

Afin de réserver un répertoire cgi-bin pour chaque utilisateur, vous pouvez utiliser une section <Directory> pour activer CGI dans un sous-répertoire particulier d'un répertoire home utilisateur.

<Directory "/home/*/public_html/cgi-bin/">
    Options ExecCGI
    SetHandler cgi-script
</Directory>

Avec la configuration ci-dessus, et en supposant que UserDir est défini à public_html, un programme CGI exemple.cgi pourra être chargé depuis ce répertoire en passant par l'URL :

http://example.com/~rbowen/cgi-bin/exemple.cgi

Permettre aux utilisateurs de modifier la configuration

Si vous voulez que vos utilisateurs puissent modifier la configuration du serveur pour ce qui concerne leur espace web, ils devront utiliser des fichiers .htaccess pour effectuer ces modifications. Assurez-vous d'avoir défini la directive AllowOverride à une valeur appropriée pour les directives dont vous voulez permettre la modification aux utilisateurs. Voir le tutoriel .htaccess pour plus de détails sur la manière dont tout ceci fonctionne.


Reverse Proxy Guide - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > How-To / Tutorials

Reverse Proxy Guide

In addition to being a "basic" web server, and providing static and dynamic content to end-users, Apache httpd (as well as most other web servers) can also act as a reverse proxy server, also-known-as a "gateway" server.

In such scenarios, httpd itself does not generate or host the data, but rather the content is obtained by one or several backend servers, which normally have no direct connection to the external network. As httpd receives a request from a client, the request itself is proxied to one of these backend servers, which then handles the request, generates the content and then sends this content back to httpd, which then generates the actual HTTP response back to the client.

There are numerous reasons for such an implementation, but generally the typical rationales are due to security, high-availability, load-balancing and centralized authentication/authorization. It is critical in these implementations that the layout, design and architecture of the backend infrastructure (those servers which actually handle the requests) are insulated and protected from the outside; as far as the client is concerned, the reverse proxy server is the sole source of all content.

A typical implementation is below:

Reverse Proxy

Related Modules Related Directives
  • mod_proxy
  • mod_proxy_balancer
  • mod_proxy_hcheck
  • ProxyPass
  • BalancerMember

Simple reverse proxying

The ProxyPass directive specifies the mapping of incoming requests to the backend server (or a cluster of servers known as a Balancer group). The simpliest example proxies all requests ("/") to a single backend:

ProxyPass "/"  "http://www.example.com/"

To ensure that and Location: headers generated from the backend are modified to point to the reverse proxy, instead of back to itself, the ProxyPassReverse directive is most often required:

ProxyPass "/"  "http://www.example.com/"
ProxyPassReverse "/"  "http://www.example.com/"

Only specific URIs can be proxied, as shown in this example:

ProxyPass "/images"  "http://www.example.com/"
ProxyPassReverse "/images"  "http://www.example.com/"

In the above, any requests which start with the /images path with be proxied to the specified backend, otherwise it will be handled locally.

Clusters and Balancers

As useful as the above is, it still has the deficiencies that should the (single) backend node go down, or become heavily loaded, that proxying those requests provides no real advantage. What is needed is the ability to define a set or group of backend servers which can handle such requests and for the reverse proxy to load balance and failover among them. This group is sometimes called a cluster but Apache httpd's term is a balancer. One defines a balancer by leveraging the <Proxy> and BalancerMember directives as shown:

<Proxy balancer://myset>
    BalancerMember http://www2.example.com:8080
    BalancerMember http://www3.example.com:8080
    ProxySet lbmethod=bytraffic
</Proxy>

ProxyPass "/images/"  "balancer://myset/"
ProxyPassReverse "/images/"  "balancer://myset/"

The balancer:// scheme is what tells httpd that we are creating a balancer set, with the name myset. It includes 2 backend servers, which httpd calls BalancerMembers. In this case, any requests for /images will be proxied to one of the 2 backends. The ProxySet directive specifies that the myset Balancer use a load balancing algorithm that balances based on I/O bytes.

Hint

BalancerMembers are also sometimes referred to as workers.

Balancer and BalancerMember configuration

You can adjust numerous configuration details of the balancers and the workers via the various parameters defined in ProxyPass. For example, assuming we would want http://www3.example.com:8080 to handle 3x the traffic with a timeout of 1 second, we would adjust the configuration as follows:

<Proxy balancer://myset>
    BalancerMember http://www2.example.com:8080
    BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
    ProxySet lbmethod=bytraffic
</Proxy>

ProxyPass "/images"  "balancer://myset/"
ProxyPassReverse "/images"  "balancer://myset/"

Failover

You can also fine-tune various failover scenarios, detailing which workers and even which balancers should accessed in such cases. For example, the below setup implements 2 failover cases: In the first, http://hstandby.example.com:8080 is only sent traffic if all other workers in the myset balancer are not available. If that worker itself is not available, only then will the http://bkup1.example.com:8080 and http://bkup2.example.com:8080 workers be brought into rotation:

<Proxy balancer://myset>
    BalancerMember http://www2.example.com:8080
    BalancerMember http://www3.example.com:8080 loadfactor=3 timeout=1
    BalancerMember http://hstandby.example.com:8080 status=+H
    BalancerMember http://bkup1.example.com:8080 lbset=1
    BalancerMember http://bkup2.example.com:8080 lbset=1
    ProxySet lbmethod=byrequests
</Proxy>

ProxyPass "/images/"  "balancer://myset/"
ProxyPassReverse "/images/"  "balancer://myset/"

The magic of this failover setup is setting http://hstandby.example.com:8080 with the +H status flag, which puts it in hot standby mode, and making the 2 bkup# servers part of the #1 load balancer set (the default set is 0); for failover, hot standbys (if they exist) are used 1st, when all regular workers are unavailable; load balancer sets are always tried lowest number first.

Balancer Manager

One of the most unique and useful features of Apache httpd's reverse proxy is the embedded balancer-manager application. Similar to mod_status, balancer-manager displays the current working configuration and status of the enabled balancers and workers currently in use. However, not only does it display these parameters, it also allows for dynamic, runtime, on-the-fly reconfiguration of almost all of them, including adding new BalancerMembers (workers) to an existing balancer. To enable these capability, the following needs to be added to your configuration:

<Location "/balancer-manager">
    SetHandler balancer-manager
    Require host localhost
</Location>

Warning

Do not enable the balancer-manager until you have secured your server. In particular, ensure that access to the URL is tightly restricted.

When the reverse proxy server is accessed at that url (eg: http://rproxy.example.com/balancer-manager/, you will see a page similar to the below:

This form allows the devops admin to adjust various parameters, take workers offline, change load balancing methods and add new works. For example, clicking on the balancer itself, you will get the following page:

Whereas clicking on a worker, displays this page:

To have these changes persist restarts of the reverse proxy, ensure that BalancerPersist is enabled.

Dynamic Health Checks

Before httpd proxies a request to a worker, it can "test" if that worker is available via setting the ping parameter for that worker using ProxyPass. Oftentimes it is more useful to check the health of the workers out of band, in a dynamic fashion. This is achieved in Apache httpd by the mod_proxy_hcheck module.

BalancerMember status flags

In the balancer-manager the current state, or status, of a worker is displayed and can be set/reset. The meanings of these statuses are as follows:

Flag | String | Description
 | Ok | Worker is available
 | Init | Worker has been initialized
D | Dis | Worker is disabled and will not accept any requests; will be automatically retried.
S | Stop | Worker is administratively stopped; will not accept requests and will not be automatically retried
I | Ign | Worker is in ignore-errors mode and will always be considered available.
H | Stby | Worker is in hot-standby mode and will only be used if no other viable workers are available.
E | Err | Worker is in an error state, usually due to failing pre-request check; requests will not be proxied to this worker, but it will be retried depending on the retry setting of the worker.
N | Drn | Worker is in drain mode and will only accept existing sticky sessions destined for itself and ignore all other requests.
C | HcFl | Worker has failed dynamic health check and will not be used until it passes subsequent health checks.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Guide HTTP/2 - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > How-To / Tutoriels

Guide HTTP/2

Ce document est le guide de l'utilisateur de l'implémentation de HTTP/2 dans Apache httpd. Cette fonctionnalité en est au stade de production, et les interfaces et directives devraient maintenant se stabiliser.

Voir aussi

  • mod_http2

Le protocole HTTP/2

HTTP/2 est une évolution du protocole de la couche application le plus utilisé au monde, HTTP. Cette évolution permet en particulier une utilisation plus efficace des ressources réseau. Il ne modifie pas les aspects fondamentaux de HTTP (sa sémantique). Entre autres, il y a toujours des requêtes, des réponses et des en-têtes. Par conséquent, si vous connaissez HTTP/1, vous connaissez déjà 95% de HTTP/2.

Beaucoup a déjà été écrit à propos de HTTP/2 et de son fonctionnement. La documentation la plus officielle est bien entendu sa RFC 7540 (ou cette version au format plus lisible). Vous trouverez ici une description des rouages de HTTP/2 dans leurs moindres détails.

Le premier document à lire lorsqu'on ne connaît pas un mécanisme n'est cependant pas sa RFC. Il est préférable de comprendre tout d'abord ce que ce mécanisme est censé faire, et seulement ensuite de lire sa RFC pour comprendre comment il fonctionne. http2 explained de Daniel Stenberg (l'auteur de curl) est un bien meilleur document pour démarrer l'étude de HTTP/2. En outre, de nouveaux langages s'ajoutent régulièrement à sa liste de traductions disponibles !

Si vous n'avez pas envie de le lire parce que vous le trouvez trop long, voici certains pièges à éviter et nouveaux termes à connaître avant de lire ce document :

  • A la différence de HTTP/1 qui est en texte pur, HTTP/2 est un protocole binaire, et alors que le premier est lisible par un humain (par exemple pour sniffer le trafic réseau), le second ne l'est pas. Voir la FAQ officielle pour plus de détails.
  • h2 correspond à HTTP/2 sur TLS (négociation de protocole via ALPN).
  • h2c correspond à HTTP/2 sur TCP.
  • Une frame ou trame est la plus petite unité de communication au sein d'une connexion HTTP/2 et comporte une en-tête et une séquence d'octets de longueur variable dont la structure correspond au type de trame. Voir la section correspondante de la documentation officielle pour plus de détails.
  • Un stream est un flux bidirectionnel de frames au sein d'une connexion HTTP/2. La notion correspondante dans HTTP/1 est un échange de messages de type requête et réponse. Voir la section correspondante de la documentation officielle pour plus de détails.
  • HTTP/2 peut gérer plusieurs streams de données sur la même connexion TCP, ce qui permet d'éviter le point de blocage classique de HTTP/1 pour les requêtes lentes, et de ne pas avoir à ouvrir de nouvelles connexions TCP pour chaque requête/réponse (les connexions persistantes ou KeepAlive avaient contourné le problème dans HTTP/1 mais ne l'avaient pas entièrement résolu)

HTTP/2 dans Apache httpd

Le protocole HTTP/2 est implémenté dans Apache httpd via un module propre, pertinemment nommé mod_http2. Ce module implémente toutes les fonctionnalités décrites par la RFC 7540 et supporte les connexions en texte pur (http:), ou sécurisées (https:). La variante texte pur se nomme 'h2c', et la variante sécurisée 'h2'. h2c peut être en mode direct ou Upgrade: via une requête initiale en HTTP/1.

Server Push est une nouvelle fonctionnalité offerte aux développeurs web par HTTP/2. La section correspondante de ce document vous indiquera comment votre application peut en tirer parti.

Compilation de httpd avec le support de HTTP/2

mod_http2 se base sur la bibliothèque de nghttp2 pour son implémentation. Pour pouvoir compiler mod_http2, libnghttp2 version 1.2.1. ou supérieure doit être installée dans votre système.

Pour déclencher la compilation de mod_http2, vous devez ajouter l'argument '--enable-http2' au script ./configure que vous exécutez à la racine de l'arborescence des sources de httpd. Si libnghttp2 est installée dans un répertoire non connu du chemin de vos bibliothèques, vous devez indiquer ce répertoire au script ./configure via l'argument '--with-nghttp2=<path>'.

Alors que cette méthode de compilation conviendra à la plupart, certains préféreront lier statiquement nghttp2 à ce module. Pour ce faire, utilisez l'argument --enable-nghttp2-staticlib-deps. Cette méthode est pratiquement la même que celle utilisée pour lier statiquement openssl à mod_ssl.

En parlant de SSL, vous devez savoir que la plupart des navigateurs ne communiqueront en HTTP/2 que sur des URLs sécurisées de type https: ; votre serveur doit donc supporter SSL. Mais de plus, votre bibliothèque SSL devra supporter l'extension ALPN. Enfin, si la bibliothèque que vous utilisez est OpenSSL, sa version devra être 1.0.2. ou supérieure.

Configuration de base

Maintenant que vous disposez d'un binaire httpd compilé avec le module mod_http2, l'activation de ce dernier nécessite un minimum de configuration supplémentaire. En premier lieu, comme pour tout module Apache, vous devez le charger :

LoadModule http2_module modules/mod_http2.so

La seconde directive que vous devez ajouter à votre fichier de configuration est

Protocols h2 http/1.1

Ceci permet de définir h2, la variante sécurisée, comme le protocole préféré pour les connexions à votre serveur. Si vous souhaitez que toutes les variantes soient disponibles, utilisez la directive suivante :

Protocols h2 h2c http/1.1

Selon l'endroit où vous placez cette directive, elle affectera l'ensemble de votre serveur, ou seulement un ou plusieurs serveurs virtuels. Vous pouvez aussi l'imbriquer comme dans l'exemple suivant :

Protocols http/1.1
<VirtualHost ...>
    ServerName test.example.org
    Protocols h2 http/1.1
</VirtualHost>

Seules les connexions en HTTP/1 seront alors permises, sauf pour le serveur virtuel test.example.org qui acceptera aussi les connexions SSL en HTTP/2.

Utilisez une chaîne d'algorithmes de chiffrement forte

La directive SSLCipherSuite doit être définie avec une chaîne d'algorithmes de chiffrement TLS forte. Même si la version actuelle de mod_http2 n'impose pas d'algorithmes de chiffrement particuliers, la plupart des clients le font. Faire pointer un navigateur vers un serveur où h2 est activé avec une chaîne d'algorithmes de chiffrement inappropriée entraînera un rejet et une retrogradation vers HTTP 1.1. C'est une erreur que l'on fait couramment lorsqu'on configure httpd pour HTTP/2 pour la première fois ; donc gardez la à l'esprit si vous voulez éviter de longues sessions de débogage ! Si vous voulez être sûr de définir une chaîne d'algorithmes de chiffrement appropriée, évitez ceux qui sont listés dans la blacklist TLS HTTP/2 .

L'ordre des protocoles indiqués est aussi important. Par défaut, le premier sera le protocole préféré. Lorsqu'un client offre plusieurs choix, c'est le plus à gauche qui sera sélectionné. Dans

Protocols http/1.1 h2

le protocole préféré sera HTTP/1 et il sera toujours sélectionné sauf si un client ne supporte que h2. Comme nous souhaitons communiquer en HTTP/2 avec les clients qui le supportent, la meilleure définition de la directive est

Protocols h2 h2c http/1.1

Toujours à propos de l'ordre des protocoles, le client a lui aussi ses propres préférences en la matière. À ce titre, si vous le souhaitez, vous pouvez configurer votre serveur pour qu'il sélectionne non plus son protocole préféré, mais au contraire le protocole préféré du client :

ProtocolsHonorOrder Off

Avec cette directive, l'ordre des protocoles que vous avez défini devient caduque et seul l'ordre défini par le client sera pris en compte.

Une dernière chose : les protocoles que vous définissez ne sont pas vérifiés quant à leurs validité ou orthographe. Vous pouvez très bien définir des protocoles qui n'existent pas, et il n'est donc pas nécessaire de filtrer les Protocoles avec des vérifications de type IfModule.

Pour des conseils plus avancés à propos de la configuration, voir la Documentation de mod_http2, et en particulier la section à propos de la consommation supplémentaire de ressources, ainsi que la section expliquant comment gérer les serveurs multiples avec certificat commun.

Configuration du MPM

Tous les modules multiprocessus (MPM) fournis avec httpd supportent HTTP/2. Cependant, si vous utilisez le MPM prefork, vous allez faire face à de sévères restrictions.

Avec le MPM prefork, mod_http2 ne traitera qu'une requête à la fois par connexion alors que les clients tels que les navigateurs internet envoient de nombreuses requêtes au même moment. Si l'une d'entre elles est longue à traiter (ou implique une longue interrogation), les autres requêtes seront mises en attente.

Par défaut, mod_http2 ne passe pas outre cette limitation pour la simple et bonne raison que le MPM prefork n'est aujourd'hui choisi que si vous exécutez des moteurs de traitement qui ne sont pas préparés pour le multithreading (par exemple qui se crashent lorsque plusieurs requêtes arrivent).

Si votre plateforme et votre installation de httpd le supportent, la meilleur solution consiste actuellement à utiliser le MPM event.

Si vous n'avez pas d'autre choix que d'utiliser le MPM prefork, mais souhaitez tout de même traiter plusieurs requêtes simultanément, vous pouvez jouer avec la directive H2MinWorkers, sans garantie que cela fonctionne.

Clients

La plupart des navigateurs modernes supportent HTTP/2, mais seulement sur des connexions SSL : Firefox v43, Chrome v45, Safari v9, iOS Safari v9, Opera v35, Chrome pour Android v49 et Internet Explorer v11 sous Windows10 (selon cette source).

D'autres clients et serveurs sont listés dans le wiki des implémentations ; entre autres des implémentations pour c, c++, common lisp, dart, erlang, haskell, java, nodejs, php, python, perl, ruby, rust, scala et swift.

De nombreuses implémentations clientes autres que les navigateurs supportent HTTP/2 en texte pur, h2c. L'une des plus efficaces d'entre elles est curl.

Outils efficaces pour déboguer HTTP/2

Le premier d'entre eux est bien entendu curl. Assurez-vous au préalable que votre version supporte HTTP/2 en vérifiant ses Fonctionnalités :

    $ curl -V
    curl 7.45.0 (x86_64-apple-darwin15.0.0) libcurl/7.45.0 OpenSSL/1.0.2d zlib/1.2.8 nghttp2/1.3.4
    Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 [...]
    Features: IPv6 Largefile NTLM NTLM_WB SSL libz TLS-SRP HTTP2

homebrew sous Mac OS :

brew install curl --with-openssl --with-nghttp2

Pour une inspection en profondeur : wireshark.

Le paquet nghttp2 inclut aussi des outils comme :

  • nghttp - permet de visualiser les trames HTTP/2 et ainsi de se faire une meilleure idée du protocole.
  • h2load - permet de tester votre serveur dans des conditions extremes.

Chrome fournit des journaux détaillés des connexions HTTP/2 via la page special net-internals page. Il y a aussi cette extension intéressante pour Chrome et Firefox qui permet d'indiquer que votre navigateur utilise HTTP/2.

Push serveur

Le protocole HTTP/2 permet au serveur de proposer (PUSH) des réponses pour lesquelles le client n'a rien demandé. La communication autour de ces réponses est du style : "voici une requête que vous n'avez jamais envoyée, et la réponse vous parviendra bientôt tout de même ..."

Il y a cependant des conditions : le client peut désactiver cette fonctionnalité et le serveur ne pourra alors lui proposer des réponses que pour les requêtes qu'il a effectivement envoyées.

Cette fonctionnalité a pour but de permettre au serveur d'envoyer au client des ressources dont il va probablement avoir besoin : par exemple une ressource css ou javascript appartenant à une page html que le client a demandée, un jeu d'images référencé par un css, etc...

Cette anticipation a pour avantage de permettre au client d'économiser le temps qu'il lui aurait fallu pour envoyer une requête, quelques millisecondes à une demi-seconde en fonction de l'éloignement du serveur. Elle a cependant pour inconvénient d'imposer au client le téléchargement de ressources qu'il possède peut-être déjà dans son cache. Bien entendu, HTTP/2 permet d'annuler prématurément de telles requêtes, mais des ressources sont tout de même gaspillées.

En résumé : il n'existe pas encore de stratégie efficace pour faire le meilleur usage de cette fonctionnalité de HTTP/2 et tout le monde en est encore au stade de l'expérimentation. À ce titre, voici des conseils pour procéder vous-même à ces expérimentations :

mod_http2 inspecte l'en-tête de la réponse et recherche les en-têtes Link sous un certain format :

Link </xxx.css>;rel=preload, </xxx.js>; rel=preload

Si la connexion supporte PUSH, ces deux ressources seront envoyées au client. En tant que développeur web vous pouvez définir ces en-têtes soit directement au niveau de la réponse de votre application, soit en configurant votre serveur via

<Location /xxx.html>
    Header add Link "</xxx.css>;rel=preload"
    Header add Link "</xxx.js>;rel=preload"
</Location>

Si vous souhaitez utiliser des liens preload sans déclencher de PUSH, vous pouvez utiliser le paramètre nopush comme suit :

Link </xxx.css>;rel=preload;nopush

Vous pouvez aussi désactiver les PUSHes pour l'ensemble de votre serveur via la directive

H2Push Off

À savoir aussi :

Le module maintient un journal des ressources ayant fait l'objet d'un PUSH pour chaque connexion (en général des condensés hash des URLs), et n'effectuera pas deux fois un PUSH pour la même ressource. Cependant, lorsque la connexion est fermée, le journal de ses PUSHes est supprimé.

Certains développeurs planchent sur la manière de permettre au client d'informer le serveur des ressources qu'il possède déjà dans son cache afin d'éviter les PUSHes pour ces dernières, mais ceci n'en est actuellement qu'à un stade très expérimental.

L' en-tête Accept-Push-Policy est un autre dispositif expérimental implémenté dans mod_http2 ; il permet au client de définir pour chaque requête quels genres de PUSHes il accepte.


Notes spécifiques aux différentes plateformes. - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Notes spécifiques aux différentes plateformes.

Microsoft Windows

Utilisation d'Apache

Ce document explique comment installer, configurer et exécuter Apache 2.4 sous Microsoft Windows.

Voir : Utilisation d'Apache avec Microsoft Windows

Compilation d'Apache

Il y a de nombreux points importants à connaître avant de se lancer dans la compilation d'Apache. Ce document en donne la description.

Voir : Compilation d'Apache pour Microsoft Windows

Systèmes de type Unix

Systèmes à base de paquets RPM (Redhat / CentOS / Fedora)

Ce document explique comment installer, configurer et exécuter Apache 2.4 sur des systèmes qui supportent le format de paquet RPM.

Voir : Utilisation d'Apache avec les systèmes à base de paquets RPM

Autres plateformes

Novell NetWare

Ce document explique comment installer, configurer et exécuter Apache 2.4 sous Novell NetWare versions 5.1 et supérieures.

Voir : Utilisation d'Apache avec Novell NetWare

EBCDIC

La version 1.3 du serveur HTTP Apache est la première à avoir été portée vers une machine de type mainframe (non-ASCII) qui utilisait le jeu de caractères EBCDIC comme jeu de caractères natif.

Avertissement :Ce document n'a pas fait l'objet d'une mise à jour pour intégrer les modifications intervenues à partir de la version 2.4 du serveur HTTP Apache. Certaines des informations qu'il contient sont toujours pertinentes, mais il est conseillé de les utiliser avec prudence.

Voir : Le portage d'Apache vers EBCDIC


Utilisation du serveur HTTP Apache sous Microsoft Windows - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Notes spécifiques à un système

Utilisation du serveur HTTP Apache sous Microsoft Windows

Ce document décrit l'installation, la configuration et l'exécution d'Apache 2.4 sous Microsoft Windows. Si vous avez des questions après avoir lu la documentation, ou si vous avez rencontré des évènements particuliers ou des rapports d'erreur, vous pouvez consultez la liste de diffusion de la communauté des utilisateurs.

Dans ce document, nous supposons que vous installez une distribution binaire d'Apache. Si vous voulez compiler Apache vous-même (par exemple pour aider au développement ou pour rechercher des bogues), référez-vous au document Compilation d'Apache pour Microsoft Windows.

Prérequis du système d'exploitation

La plate-forme Windows de base pour l'exécution d'Apache 2.4 est Windows 2000 ou supérieur. Veillez à toujours vous procurer et installer le dernier service pack afin d'éviter les bogues du système d'exploitation.

Les versions du serveur HTTP Apache supérieures à 2.2 ne fonctionneront sous aucun système d'exploitation d'une version antérieure à Windows 2000.

Téléchargement d'Apache pour Windows

Le projet du serveur HTTP Apache proprement dit ne fournit pas de distribution binaire mais seulement le code source. Certains membres du projet peuvent mettre à disposition des paquets binaires à titre individuel, mais ceux-ci n'ont pas vocation à être distribués publiquement.

Si vous n'êtes pas en mesure de compiler le serveur HTTP Apache vous-même, vous pouvez vous procurer un paquet binaire auprès des nombreuses distributions disponibles sur Internet.

Quelques solutions populaires pour déployer Apache httpd, et éventuellement PHP et MySQL sous Microsoft Windows :

  • ApacheHaus
  • Apache Lounge
  • BitNami WAMP Stack
  • WampServer
  • XAMPP

Personnaliser Apache pour Windows

La configuration d'Apache est enregistrée dans les fichiers du sous-répertoire conf. Ce sont les même fichiers que ceux utilisés pour configurer la version Unix, mais il y a quelques directives spécifiques à Apache pour Windows. Voir l'index des directives pour la liste des directives disponibles.

Les principales spécificités d'Apache pour Windows sont :

  • Comme Apache pour Windows est un programme multithread, il ne lance pas de processus séparé pour chaque requête, comme Apache peut le faire sous Unix. En fait, il n'y a en général que deux processus Apache en exécution : un processus parent, et un processus enfant qui traite les requêtes. Chaque requête est traitée par un thread séparé au sein du processus enfant.

    Les directives de gestion de processus diffèrent également :

    MaxConnectionsPerChild : comme dans la version Unix, cette directive contrôle le nombre de connexions qu'un processus enfant particulier va traiter avant de s'arrêter. Cependant, à la différence d'Unix, un processus de remplacement n'est pas instantanément disponible. Utilisez la définition par défaut MaxConnectionsPerChild 0, sauf si vous risquez de manquer de mémoire dans des modules tiers ou dans des applications in-process.

    Attention : le fichier de configuration du serveur est rechargé lorsqu'un nouveau processus enfant est démarré. En conséquence, si vous avez modifié httpd.conf, le nouveau processus enfant peut ne pas démarrer, ou vous pouvez obtenir des résultats inattendus.

    ThreadsPerChild : il s'agit d'une nouvelle directive. Elle indique au serveur le nombre de threads qu'il doit utiliser. Elle définit le nombre maximum de connexions simultanées que le serveur peut gérer ; vous devez donc vous assurer que ce nombre soit suffisamment grand pour les besoins de votre site. La valeur par défaut ThreadsPerChild 150 est recommandée, mais doit être ajustée à la valeur maximale estimée de connexions simultanées à accepter.

  • Les directives qui acceptent des noms de fichiers comme arguments doivent utiliser des noms de fichiers Windows et non Unix. Cependant, comme Apache peut interpréter les anti-slashes comme des séquences d'échappement de caractères, vous devez absolument utiliser des slashes dans les noms de chemins à la place des anti-slashes.

  • Alors que les noms de fichiers sont en général insensibles à la casse sous Windows, les URLs sont encore sensibles à la casse en interne avant d'être mises en correspondance avec le système de fichiers. Par exemple, les directives <Location>, Alias, et ProxyPass utilisent toutes des arguments sensibles à la casse. Pour cette raison, il est particulièrement recommandé d'utiliser la directive <Directory> lorsqu'on désire limiter l'accès à certains contenus du système de fichiers, car cette directive s'applique à tout contenu d'un répertoire, sans tenir compte de la manière dont on y accède. Pour vous assurer que seules des minuscules sont utilisées dans les URLs, vous pouvez utiliser ceci :

    RewriteEngine On
RewriteMap lowercase int:tolower
RewriteCond "%{REQUEST_URI}" "[A-Z]"
RewriteRule "(.*)" "${lowercase:$1}" [R,L]

  • Lors de son exécution, Apache n'a besoin d'un accès en écriture qu'au répertoire des journaux et à toute arborescence de répertoires de cache configurée. Suite au problème d'insensibilité à la casse et au format de noms courts 8.3, Apache doit valider tous les noms de chemins fournis. Cela signifie que chaque répertoire qu'Apache évalue doit avoir les droits en lecture, listage et parcours, et ceci depuis la racine jusqu'aux feuilles. Si Apache2.4 est installé dans C:\Program Files, le répertoire racine, Program Files et Apache2.4 doivent tous être visibles pour Apache

  • Apache peut charger divers modules sans qu'il soit nécessaire de recompiler le serveur. Si Apache est compilé normalement, il va installer de nombreux modules optionnels dans le répertoire \Apache2.4\modules. Pour activer ces modules ou d'autres modules, on doit utiliser la directive LoadModule. Par exemple, pour activer le module status, ajoutez la ligne suivante (en plus des directives d'activation de status dans access.conf) :

    LoadModule status_module modules/mod_status.so

    Des informations sont aussi à votre disposition pour créer des modules chargeables

  • Apache peut aussi charger des extensions ISAPI (Internet Server Application Programming Interface), comme celles qu'utilise Microsoft IIS et d'autres serveurs Windows. Voir ici pour plus d'informations. Notez qu'Apache ne peut pas charger de filtres ISAPI, et que les gestionnaires ISAPI contenant des extensions de fonctionnalités Microsoft ne fonctionneront pas.

  • Pour les scripts CGI, la méthode qu'utilise Apache pour déterminer l'interpréteur du script est configurable grâce à la directive ScriptInterpreterSource

  • Comme il est souvent difficile de gérer des fichiers avec des noms du style .htaccess sous Windows, vous avez tout intérêt à changer le nom de ce fichier de configuration par répertoire à l'aide de la directive AccessFilename.

  • Toute erreur survenant au cours du processus de démarrage d'Apache est enregistrée dans le journal des évènements de Windows si l'on est sous Windows NT. Ce mécanisme fonctionne comme une sauvegarde pour les situations où Apache n'est pas encore prêt à utiliser le fichier error.log. Vous pouvez consulter le journal des évènements applicatifs Windows en utilisant l'observateur d'évènements : Démarrage - Paramètres - Panneau de configuration - Outils d'administration - Observateur d'évènements.

Exécuter Apache en tant que service

Apache fournit un utilitaire nommé Apache Service Monitor (Moniteur du service Apache). Grâce à lui, vous pouvez voir et gérer l'état de tous les services Apache installés sur toutes les machines du réseau. Pour pouvoir gérer un service Apache avec le moniteur, vous devez d'abord installer le service (soit automatiquement au cours de l'installation, soit manuellement).

Vous pouvez installer Apache en tant que service Windows NT à partir de la ligne de commandes et depuis le sous-répertoire Apache bin comme suit :

httpd.exe -k install

Si vous avez installé plusieurs services Apache sur votre ordinateur, vous devrez spécifier le nom du service que vous voulez installer en utilisant la commande suivante (notez que si vous spécifiez un nom durant l'installation, vous devrez aussi le spécifier pour toute opération comportant l'option -k) :

httpd.exe -k install -n "Nom-service"

Si un service doit utiliser un fichier de configuration spécifique, utilisez ceci :

httpd.exe -k install -n "Nom-service" -f "c:\fichiers\Nom-service.conf"

Si vous utilisez la première commande sans paramètre particulier, excepté -k install, le service aura pour nom Apache2.4 et le fichier de configuration sera censé être conf\httpd.conf.

Supprimer un service Apache est très simple. Utilisez simplement :

httpd.exe -k uninstall

On peut spécifier un service Apache particulier en utilisant :

httpd.exe -k uninstall -n "Nom service"

Normalement, le démarrage, le redémarrage et l'arrêt d'un service Apache s'effectuent via le Moniteur de Service Apache, ou en utilisant des commandes telles que NET START Apache2.4 et NET STOP Apache2.4, ou encore via le gestionnaire de services standard de Windows. Avant de démarrer Apache en tant que service dans quelque but que ce soit, vous devez tester le fichier de configuration du service en utilisant :

httpd.exe -n "Nom-service" -t

Vous pouvez aussi contrôler un service Apache à l'aide de ses options de ligne de commande. Avec cette méthode, pour démarrer un service Apache installé, vous utiliserez :

httpd.exe -k start -n "Nom-Service"

Pour arrêter un service Apache via les options de lignes de commande, utilisez ceci :

httpd.exe -k stop -n "Nom-Service"

ou

httpd.exe -k shutdown -n "Nom-Service"

Vous pouvez aussi redémarrer un service en exécution et le forcer à relire son fichier de configuration en utilisant :

httpd.exe -k restart -n "Nom-Service"

Par défaut, tous les services Apache sont configurés pour s'exécuter sous l'utilisateur system (le compte LocalSystem). Le compte LocalSystem n'a pas de privilèges sur votre réseau, que ce soit via un mécanisme sécurisé de Windows, y compris le système de fichiers, des tubes nommés, DCOM ou des RPC sécurisés. Il a cependant des privilèges élevés en local.

N'accordez jamais de privilèges réseau au compte LocalSystem ! Si Apache doit pouvoir accéder à des ressources réseau, créez un compte séparé pour Apache comme indiqué ci-dessous.

Il est fortement fortement conseillé aux utilisateurs de créer un compte séparé pour exécuter le(s) service(s) Apache, et même obligatoire si vous devez accéder à des ressources réseau via Apache.

  1. Créez un compte d'utilisateur du domaine normal, et assurez-vous de retenir son mot de passe.
  2. Accordez à l'utilisateur nouvellement créé les privilèges Log on as a service et Act as part of the operating system. Sous Windows NT 4.0, ces privilèges sont accordés via le Gestionnaire des utilisateurs du Domaine, mais sous Windows 2000 et XP, vous aurez plutôt intérêt à utiliser une GPO pour propager ces configurations. Vous pouvez aussi effectuer ces réglages via la Politique de Sécurité Locale intégrée à la MMC.
  3. Vérifiez que le compte nouvellement créé est membre du groupe Utilisateurs
  4. Accordez à ce compte les droits Lecture et Exécution (RX) sur tous les documents et répertoires de scripts (htdocs et cgi-bin par exemple), et aussi sur l'exécutable binaire httpd.exe.
  5. Accordez aussi à ce compte les droits de modification sur le répertoire logs.
Il est en général de bonne pratique d'accorder à l'utilisateur sous lequel le service Apache s'exécute les droits en lecture et exécution (RX) sur l'ensemble du répertoire Apache2.4, sauf pour le sous-répertoire logs, sur lequel l'utilisateur doit avoir au moins les droits de modification (RWXD).

Si vous permettez à ce compte de se connecter en tant qu'utilisateur et service, vous pouvez ouvrir une session sous ce compte et vérifier s'il a bien le droit d'exécuter les scripts, de lire les pages web, et si vous pouvez démarrer Apache à partir d'une console Windows. Si tout fonctionne, et si vous avez suivi les étapes ci-dessus, Apache devrait s'exécuter en tant que service sans problème.

Le code d'erreur 2186 indique probablement qu'Apache ne peut pas accéder à une ressource réseau nécessaire, et que vous devez revoir la configuration "Log On As" (Se connecter en tant que ...) du service.

Lorsqu'Apache démarre en tant que service, il se peut que vous obteniez un message d'erreur du Gestionnaire de Services Windows. Par exemple, si vous essayez de démarrer Apache en utilisant l'applet Services du Panneau de configuration de Windows, vous pouvez obtenir le message suivant :

Could not start the Apache2.4 service on \\COMPUTER
Error 1067; The process terminated unexpectedly.

Vous obtiendrez cette erreur à caractère général pour tout problème survenant au cours du démarrage du service Apache. Afin de déterminer exactement la cause du problème, vous devez suivre les instructions permettant d'exécuter Apache pour Windows depuis la ligne de commande.

Si vous rencontrez des problèmes avec le service, il est conseillé de suivre les instructions ci-dessous afin d'essayer de démarrer httpd.exe depuis une console, et d'analyser les erreurs plutôt que vous démener à essayer de démarrer le service.

Exécuter Apache depuis la console

Il est en général recommandé d'exécuter Apache en tant que service, mais il est parfois plus simple d'utiliser la ligne de commande, en particulier au cours de la configuration initiale et les tests.

Pour exécuter Apache depuis la ligne de commande et en tant qu'application de console, utilisez la commande suivante :

httpd.exe

Apache va démarrer, et continuera son exécution jusqu'à ce qu'on l'arrête en tapant Ctrl-C.

Vous pouvez également démarrer Apache via le raccourci "Démarrer Apache dans une console" placé dans Démarrer --> Programmes --> Apache HTTP Server 2.4.xx --> Control Apache Server au cours de l'installation. Ceci va ouvrir une console Windows, et y démarrer Apache. Si vous n'avez pas installé Apache en tant que service, la fenêtre Windows restera ouverte jusqu'à ce que vous arrêtiez Apache en tapant Ctrl-C dans cette fenêtre. Le serveur va alors s'arrêter au bout de quelques secondes. Cependant, si vous avez installé Apache en tant que service, c'est ce dernier que le raccourci ci-dessus va lancer. Si le service Apache est déjà en cours d'exécution, le raccourci va rester sans effet.

Si Apache s'exécute en tant que service, vous pouvez l'arrêter en ouvrant une autre console et en entrant :

httpd.exe -k shutdown

Plutôt que de lancer Apache à partir d'une console, il est préférable de l'exécuter en tant que service car dans ce cas, il termine proprement les opérations en cours avant de s'éteindre.

Si le serveur a été lancé depuis une console, vous ne pouvez l'arrêter qu'en pressant la combinaison de touches Ctrl-C dans la même fenêtre.

Vous pouvez aussi redémarrer Apache. Ceci le force à recharger son fichier de configuration. Toute opération en cours peut être achevée sans interruption. Pour redémarrer Apache, vous pouvez soit taper Control-Break dans la fenêtre de console que vous avez utilisée pour le démarrer, soit entrer :

httpd.exe -k restart

si le serveur s'exécute en tant que service.

Note pour les utilisateurs familiers de la version Unix d'Apache : les commandes ci-dessus représentent pour Windows l'équivalent des commandes kill -TERM pid et kill -USR1 pid. L'option de ligne de commande -k a été choisie à titre de rapprochement avec la commande kill utilisée sous Unix.

Si la fenêtre de la console Apache se ferme immédiatement ou inopinément après le démarrage d'Apache, ouvrez une console Windows depuis le menu Démarrer --> Programmes. Placez-vous dans le répertoire d'installation d'Apache, tapez la commande httpd.exe, et observez le message d'erreur. Allez ensuite dans le répertoire des journaux, et visualisez le fichier error.log pour détecter d'éventuelles erreurs de configuration. Si Apache a été installé dans C:\Program Files\Apache Software Foundation\Apache2.4\, vous pouvez entrer ce qui suit :

c:
cd "\Program Files\Apache Software Foundation\Apache2.4\bin"
httpd.exe

Attendez ensuite qu'Apache s'arrête ou tapez Ctrl-C. Entrez alors la commande suivante :

cd ..\logs
more < error.log

Lorsqu'on travaille avec Apache, il est important de comprendre comment ce dernier trouve son fichier de configuration. Vous pouvez spécifier un fichier de configuration à partir de la ligne de commande de deux façons :

  • L'option -f permet de spécifier un chemin absolu ou relatif vers un fichier de configuration particulier :

    (sous Windows 9x, il est recommandé d'utiliser la ligne de commande à cause du manque de fiabilité du support des services fourni par ce système).

    httpd.exe -f "c:\fichiers-de-mon-serveur\autre-config.conf"

    ou

    httpd.exe -f fichiers-de-mon-serveur\autre-config.conf

  • L'option -n permet de spécifier le service Apache installé dont le fichier de configuration doit être utilisé :

    httpd.exe -n "Nom-service"

Dans les deux cas, la directive ServerRoot doit être correctement définie dans le fichier de configuration.

Si vous ne spécifiez aucun fichier de configuration à l'aide des options -f ou -n, Apache utilisera le nom du fichier de configuration compilé dans le serveur, en général conf\httpd.conf. Ce chemin codé en dur est relatif au répertoire d'installation. Vous pouvez vérifier ce chemin à partir de la valeur de l'étiquette SERVER_CONFIG_FILE en invoquant Apache avec l'option -V, comme ceci :

httpd.exe -V

Apache va ensuite essayer de déterminer la valeur de son ServerRoot en effectuant les recherches suivantes, dans cet ordre :

  1. Une directive ServerRoot via l'option de ligne de commande -C.
  2. L'option de ligne de commande -d.
  3. Le répertoire de travail courant.
  4. Une entrée de la base de registre créée dans le cas d'une installation binaire.
  5. La racine des documents (DocumentRoot) codée en dur dans le serveur. Elle correspond par défaut à /apache, et vous pouvez le vérifier en tapant httpd.exe -V et en recherchant l'étiquette HTTPD_ROOT.

Si vous n'avez pas effectué d'installation binaire, dans certains scénarios, Apache va signaler l'absence de cette clé de registre. On peut passer outre cet avertissement si le serveur a été en mesure de trouver son fichier de configuration d'une autre manière.

La valeur de cette clé correspond au répertoire ServerRoot qui contient lui-même le sous-répertoire conf. Lors de son démarrage, Apache lit le fichier httpd.conf à partir de ce répertoire. Si ce fichier contient une directive ServerRoot qui spécifie un répertoire différent de celui que contient la clé de registre ci-dessus, Apache oubliera la clé de registre, et utilisera le répertoire spécifié par le fichier de configuration. Si vous déplacez le répertoire Apache ou ses fichiers de configuration, il est vital de mettre à jour la directive ServerRoot dans httpd.conf afin de refléter la nouvelle localisation.

Vérification de l'installation

Une fois Apache démarré (soit à partir d'une console Windows, soit en tant que service), ce dernier va se mettre à l'écoute sur le port 80 (à moins que vous ayiez modifié la directive Listen dans les fichiers de configuration ou que vous ayiez installé Apache pour l'utilisateur courant seulement). Pour vous connecter au serveur et accéder à la page par défaut, lancez un navigateur et entrez cette URL :

http://localhost/

Apache devrait renvoyer une page de bienvenue et vous devriez voir s'afficher "It Works!". Si rien ne se passe ou si vous obtenez une erreur, consultez le fichier error.log dans le sous-répertoire logs. Si votre serveur n'est pas connecté au réseau, ou si vous avez de sérieux problèmes avec la configuration de votre DNS (Domain Name Service), vous devez utiliser cette URL :

http://127.0.0.1/

Si Apache écoute un port non standard, vous devez le préciser explicitement dans l'URL :

http://127.0.0.1:8080/

Après que votre installation de base fonctionne, vous devez la configurer correctement en éditant les fichiers du sous-répertoire conf. Encore une fois, si vous modifiez la configuration du service Apache sous Windows NT, essayez d'abord de redémarrer le service depuis la ligne de commande afin de vous assurer de l'absence d'erreur.

Comme Apache ne peut pas partager le même port avec d'autres applications TCP/IP, il se peut que vous soyez amené à arrêter, désinstaller ou reconfigurer certains services avant de démarrer Apache. Ces services entrant en conflit avec Apache comprennent les autres serveurs WWW, certaines implémentations de pare-feu, et même certaines applications client (comme Skype) qui utilisent le port 80 afin de contourner les pare-feu.

Configuration de l'accès aux ressources réseau

L'accès à des fichiers par le réseau peut être spécifié via deux mécanismes fournis par Windows :

Association de lettres de lecteur
Par exemple, Alias "/images/" "Z:/"
chemins UNC
Par exemple, Alias "/images/" "//imagehost/www/images/"

L'association de lettres de lecteur permet à l'administrateur de maintenir une correspondance avec une certaine machine et un certain chemin en dehors de la configuration d'Apache httpd. Cependant, ces associations ne sont possibles que dans le cadre des sessions interactives, et ne sont pas directement disponibles pour Apache httpd lorsqu'il est démarré en tant que service. N'utilisez par conséquent que des chemins UNC pour les ressources réseau dans httpd.conf, de façon à ce que les ressources soient accessibles quelle que soit la manière dont Apache httpd a été démarré (des procédures exotiques et probablement sujettes aux erreurs peuvent permettre de contourner la restriction due aux associations de lettres de lecteur, mais leur utilisation est déconseillée).

Exemple de DocumentRoot avec chemin UNC

DocumentRoot "//dochost/www/html/"

Exemple de DocumentRoot avec adresse IP dans le chemin UNC

DocumentRoot "//192.168.1.50/docs/"

Exemple d'Alias et répertoire correspondant avec chemin UNC

Alias "/images/" "//imagehost/www/images/"

<Directory "//imagehost/www/images/">
#...
<Directory>

Lorsqu'Apache s'exécute en tant que service, vous devez créer un compte spécifique afin de pouvoir accéder aux ressources réseau, comme décrit ci-dessus.

Personnalisation sous Windows

  • Si on utilise un grand nombre de redirections de journaux via des pipes, il est souvent nécessaire d'augmenter la taille de la mémoire du bureau ("desktop heap"). Pour une information plus détaillée, veuillez vous reporter à la documentation sur les redirections de journaux.


Compiler Apache pour Microsoft Windows - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Notes spécifiques à certaines plates-formes

Compiler Apache pour Microsoft Windows

Il y a de nombreux points importants à connaître avant de compiler Le serveur HTTP Apache pour Microsoft Windows. Avant de commencer, lisez le document Utiliser le serveur HTTP Apache avec Microsoft Windows.

httpd peut être compilé sous Windows en utilisant une chaîne de compilation basée sur cmake, ou à partir de fichiers projet Visual Studio maintenus par les développeurs de httpd. La chaîne de compilation basée sur cmake supporte directement davantage de versions de Visual Studio, mais possède actuellement des fonctionnalités très limitées.

Prérequis

Pour compiler Apache, l'environnement doit satisfaire aux conditions suivantes :

  • Espace disque

    Assurez-vous de disposer d'un minimum de 200 Mo d'espace disque disponible. Après l'installation, Apache occupe environ 80 Mo d'espace disque, plus l'espace réservé aux journaux et au cache, la taille de ces derniers pouvant augmenter rapidement. Les besoins réels en espace disque dépendent étroitement de la configuration choisie et des bibliothèques ou modules tiers installés, en particulier lorsqu'OpenSSL est mis en oeuvre. Comme de nombreux fichiers sont au format texte et donc facilement compressibles, l'utilisation de la compression du système de fichiers NTFS divise ces besoins par deux.

  • Correctifs requis

    Le binaire httpd est compilé à l'aide de nombreux correctifs appliqués aux paquets tiers, ce qui permet de s'assurer que le code fourni est bien compilable et déboguable. Ces correctifs sont disponibles à http://www.apache.org/dist/httpd/binaries/win32/patches_applied/, et il est recommandé de les appliquer afin d'obtenir un résultat identique aux binaires "officiels" distribués par l'ASF.

  • Microsoft Visual C++ 6.0 (Visual Studio 97) ou supérieur.

    Apache peut être compilé en utilisant l'outil ligne de commande, ou depuis l'espace de travail IDE Visual Studio. Pour la compilation depuis la ligne de commandes, l'environnement doit comporter les variables the PATH, INCLUDE, LIB, ainsi que d'autres variables qui peuvent être définies via le script vcvars32.bat :

    Vous pouvez vous procurer le paquet du Processeur Visual Studio pour votre ancienne version de Visual Studio, ou une version complète (et non Express) d'une édition plus récente de Visual Studio pour l'assembleur ml.exe. Ceci vous permettra, si vous le souhaitez, de compiler OpenSSL en utilisant une implémentation du code d'assemblage plus efficace.
    Seule la chaîne d'outils de compilation de Microsoft est supportée de manière suivie par les contributeurs actifs à httpd. Bien que le projet accepte régulièrement des correctifs pour s'assurer que MinGW et d'autre outils de compilation fonctionnent, ou même pour les améliorer, ils ne sont pas maintenus de manière suivie et sont même souvent hors d'état de fonctionner à certains stades du développement normal.

  • Le SDK de la plate-forme Windows mis à jour, février 2003 ou plus récent.

    Un SDK approprié pour la plate-forme Windows est inclus par défaut dans les versions complètes (et non Express/lite) de Visual C++ 7.1 (Visual Studio 2002) et supérieures ; les utilisateurs peuvent ignorer ces étapes, à moins qu'ils aient choisi d'utiliser une version plus récente ou différente du SDK.

    Pour pouvoir utiliser Visual C++ 6.0 or 7.0 (Studio 2000 .NET), l'environnement du SDK de la plate-forme doit être préparé en utilisant le script setenv.bat (installé par le SDK de la plate-forme) avant de lancer la compilation en ligne de commande ou l'interface GUI msdev/devenv. L'installation du SDK de la plate-forme pour les versions Express de Visual Studio (2003 et supérieures) devrait ajuster l'environnement par défaut de manière appropriée.

    "c:\Program Files\Microsoft Visual Studio\VC98\Bin\VCVARS32"
    "c:\Program Files\Platform SDK\setenv.bat"

  • Perl et awk

    De nombreuses étapes recommandées ici nécessitent un interpréteur perl durant le processus de préparation de la compilation.

    Pour installer Apache à partir du système de compilation, de nombreux fichiers sont modifiés via l'utilitaire awk.exe. awk effectue la modification des fichiers au moment de l'installation ; il a été choisi car il nécessite un téléchargement de petite taille (par rapport à Perl ou WSH/VB). Le site de Brian Kernighan http://www.cs.princeton.edu/~bwk/btl.mirror/ propose un binaire précompilé pour Win32, http://www.cs.princeton.edu/~bwk/btl.mirror/awk95.exe, que vous devez enregistrer sous le nom awk.exe (plutôt que awk95.exe).

    Si awk.exe n'est pas trouvé, la cible install du fichier Makefile.win n'effectuera aucune substitution dans les fichiers .conf installés. Vous devez modifier manuellement les fichiers .conf installés afin de permettre au serveur de démarrer. Recherchez et remplacez toutes les balises "@token@" par une valeur appropriée.
    L'IDE Visual Studio ne trouvera le chemin de awk.exe que dans la variable PATH, ou dans le chemin des exécutables spécifié par l'option de menu Tools -> Options -> (Projects ->) Directories. Assurez-vous qu'awk.exe est bien dans votre chemin système.
    Notez aussi, si vous utilisez les outils Cygwin (http://www.cygwin.com/), que l'utilitaire awk de nomme gawk.exe et que le fichier awk.exe est en fait un lien symbolique vers le fichier gawk.exe. Le shell de commandes Windows ne reconnaît pas les liens symboliques, et par conséquent la compilation d'InstallBin échouera. Pour contourner le problème, vous pouvez supprimer le lien awk.exe de l'installation de Cygwin, et copier gawk.exe vers awk.exe. Notez aussi que les portages cygwin/mingw de gawk 3.0.x étaient bogués ; veuillez par conséquent effectuer une mise à jour vers la version 3.1.x avant l'utilisation de tout portage de gawk.

  • [Optionnel] bibliothèque zlib (pour le module mod_deflate)

    Zlib doit être installée dans un sous-répertoire du répertoire srclib et nommé zlib. Elle doit être compilée directement à cette place. Zlib est disponible à l'adresse http://www.zlib.net/ -- le fonctionnement correct du module mod_deflate a été vérifié avec la version 1.2.3.

    nmake -f win32\Makefile.msc
    nmake -f win32\Makefile.msc test

  • [Optionnel] Bibliothèques OpenSSL (pour le module mod_ssl et ab.exe avec le support ssl)

    La bibliothèque OpenSSL est un logiciel de chiffrement. Le pays dans lequel vous résidez peut imposer des restrictions à l'importation, la possession, l'utilisation, et/ou la réexportation vers un autre pays des logiciels de chiffrement. AVANT d'utiliser tout logiciel de chiffrement, veuillez consulter la législation de votre pays, les règles et politiques d'importation, de possession, ou d'utilisation, et de réexportation des logiciels de chiffrement, afin de déterminer si vous en avez le droit. Voir http://www.wassenaar.org/ pour plus de détails.

    La configuration et la compilation d'OpenSSL nécessite l'installation de perl.

    Pour pouvoir compiler mod_ssl ou le projet abs.exe, qui devient ab.c avec le support SSL activé, vous devez télécharger OpenSSL à l'adresse http://www.openssl.org/source/, et l'installer dans un sous-répertoire du répertoire srclib que vous nommerez openssl. Afin de préparer OpenSSL à la liaison avec le module Apache mod_ssl ou abs.exe, et désactiver les fonctionnalités d'Openssl grévées de brevets, vous pouvez utiliser la commande de compilation suivante :

    perl Configure no-rc5 no-idea enable-mdc2 enable-zlib VC-WIN32 -Ipath/to/srclib/zlib -Lpath/to/srclib/zlib
    ms\do_masm.bat
    nmake -f ms\ntdll.mak

    Il est déconseillé d'utiliser zlib-dynamic, car la charge de la décompression des flux SSL est alors transférée à la première requête qui doit charger la dll zlib. Notez que le correctif proposé active le drapeau -L afin de pouvoir fonctionner avec les compilations Windows, corrige le nom de zdll.lib et s'assure que les fichiers .pdb sont générés afin de pouvoir résoudre les problèmes. Si l'assembleur n'est pas installé, vous devez ajouter no-asm ci-dessus et utiliser le script ms\do_ms.bat à la place de ms\do_masm.bat.

  • [Optionnel] Bibliothèques de bases de données (pour mod_dbd et mod_authn_dbm)

    La bibliothèque apr-util fournit un accès aux fonctionnalités clients dbm (base de données à base de clés) et dbd (base de données à base de requêtes) au serveur httpd et à certains de ses modules, comme les modules d'authentification et d'autorisation. Les fournisseurs sdbm dbm et odbc dbd sont compilés automatiquement.

    Le support dbd inclut le paquet instantclient Oracle, MySQL, PostgreSQL et sqlite. Par exemple, pour les compiler tous, définissez LIB de façon à inclure le chemin des bibliothèques, INCLUDE de façon à inclure le chemin des en-têtes, et PATH de façon à inclure le chemin des dll et bin de chacun des quatre SDK, et définissez la variable d'environnement DBD_LIST de façon à indiquer au processus de compilation quels SDKs pilotes clients du sont correctement installés ; par exemple :

    set DBD_LIST=sqlite3 pgsql oracle mysql

    De manière similaire, le support dbm peut être étendu avec DBM_LIST pour compiler un fournisseur Berkeley DB (db) et/ou un fournisseur gdbm, en configurant tout d'abord de la même manière LIB, INCLUDE et PATH afin de s'assurer que les bibliothèques et en-têtes de la bibliothèque client sont bien disponibles.

    set DBM_LIST=db gdbm

    En fonction du choix des distributions de bases de données, il peut s'avérer nécessaire de modifier le nom des cibles de l'édition de liens (par exemple gdbm.lib à la place de libgdb.lib) listées dans les fichiers .dsp/.mak des répertoires srclib\apr-util\dbd ou ...\dbm correspondants.

    Voir le fichier README-win32.txt pour plus d'informations à propos de l'obtention des différents SDKs pilotes de bases de données.

Compilation à partir des sources Unix

Le projet du serveur HTTP Apache à pour politique de ne fournir que des sources de type Unix. Les paquets source de type Windows disponibles en téléchargement ont été élaborés par des contributeurs, et ne seront pas forcément reconduits pour toutes les versions. Vous pouvez cependant compiler le serveur sous Windows à partir des sources Unix en ajoutant quelques étapes supplémentaires.

  1. Téléchargez et ouvrez le tarball source Unix de la dernière version du serveur HTTP Apache.
  2. Téléchargez et ouvrez le tarball source Unix de la dernière version de APR, APR-Util et APR-Iconv, et copier l'arborescence obtenue dans httpd-2.x.x\srclib\apr, httpd-2.x.x\srclib\apr-util et httpd-2.x.x\srclib\apr-iconv
  3. Ouvrez la console et placez-vous au niveau du répertoire httpd-2.x.x
  4. Exécutez l'utilitaire de conversion de fins de ligne

perl srclib\apr\build\lineends.pl

Vous pouvez maintenant compiler le serveur via l'environnement de développement Visual Studio en utilisant l'IDE. Les compilations du serveur en ligne de commande ne sont possibles avec des sources de type Unix que si vous exportez les fichiers .mak comme indiqué ci-dessous.

Compilation à partir de la ligne de commandes

Makefile.win est le makefile principal ou racine d'Apache. Pour compiler Apache sous Windows, utilisez simplement une des commandes suivantes pour compiler la version release ou debug :

nmake /f Makefile.win _apacher

nmake /f Makefile.win _apached

Ces deux commandes effectuent la compilation d'Apache. Cependant, avec la deuxième, les fichiers résultants ne seront pas optimisés, ce qui va faciliter l'examen pas à pas du code pour trouver des bogues et résoudre les problèmes.

Vous pouvez indiquer vos choix en matière de fournisseurs dbd et dbm à l'aide des variables (d'environnement) additionnelles de make DBD_LIST et DBM_LIST ; voir les commentaires à propos des [Optionnel] Bibliothèques de bases de données ci-dessus. Consultez les commentaires initiaux dans Makefile.win pour plus d'options pouvant être fournies lors de la compilation.

Compilation depuis l'espace de travail IDE de Developer Studio

Apache peut aussi être compilé depuis l'environnement de développement Visual Studio de VC++. Pour simplifier ce processus, l'espace de travail Visual Studio Apache.dsw est fourni. Cet espace de travail expose la liste complète des projets .dsp actifs nécessaires à l'installation binaire complète d'Apache. Il inclut les dépendances entre projets afin que ces derniers soient compilés selon l'ordre approprié.

Ouvrez l'espace de travail Apache.dsw, et sélectionnez InstallBin (compilation Release ou Debug, selon vos souhaits) comme Active Project. InstallBin provoque la compilation de tous les projets concernés, puis invoque Makefile.win pour installer les exécutables et dlls compilés. Vous pouvez modifier la valeur de INSTDIR= via la configuration de InstallBin, onglet Général, entrée ligne de commandes de compilation. La valeur par défaut de INSTDIR est le répertoire /Apache2. Si vous désirez effectuer un test de compilation (sans installation), sélectionnez le projet BuildBin.

Les fichiers projets .dsp sont distribués au format Visual Studio 6.0 (98). Visual C++ 5.0 (97) les reconnaît. Les utilisateurs de Visual Studio 2002 (.NET) et versions supérieures doivent convertir Apache.dsw et les fichiers .dsp en un projet Apache.sln, ainsi que les fichiers .msproj ; assurez-vous de reconvertir le fichier .msproj si l'un des fichiers source .dsp est modifié ! Cette opération est vraiment très simple, il suffit de réouvrir Apache.dsw dans l'IDE VC++ 7.0 et de le reconvertir.

Il y a une erreur dans la conversion .vcproj des fichiers .dsp. devenv.exe interprète mal le drapeau /D pour les drapeaux RC contenant de grandes /D'éfinitions entourées de guillemets, et contenant elles-mêmes des espaces. Ainsi, la commande :

perl srclib\apr\build\cvtdsp.pl -2005

va convertir les drapeaux /D pour les drapeaux RC afin d'utiliser une syntaxe alternative, interprétable ; malheureusement, cette syntaxe n'est pas supportée par Visual Studio 97 ou ses fichiers .mak exportés. Ces drapeaux /D permettent de transmettre la longue description des fichiers de mod_apachemodule.so à leurs compilations d'identificateur de version de ressource .rc partagée.
Compilation avec OpenSSL versions 1.1.0 et supérieures Suite à une modification de la structure de compilation d'OpenSSL à partir de la version 1.1.0, vous devez convertir les fichiers dsp concernés via la commance cvtdsp.pl fournie par APR versions 1.6 et supérieures :

perl srclib\apr\build\cvtdsp.pl -ossl11

Les utilisateurs de Visual Studio 2002 (.NET) et versions supérieures doivent aussi utiliser la boîte de dialogue Configuration Manager du menu Build pour décocher les deux versions Debug et Release des modules mod_ssl et mod_deflate pour abs. Ces modules sont compilés en invoquant nmake ou directement l'IDE avec la cible BinBuild pour compiler ces modules de manière conditionnelle si les sous-répertoires de srclib openssl et/ou zlib existent, et en fonction des définitions des variables d'environnement DBD_LIST et DBM_LIST.

Export des fichiers .mak de la ligne de commandes

Les fichiers .mak exportés posent plus de problèmes, mais les utilisateurs de Visual C++ 5.0 en ont besoin pour compiler mod_ssl, abs (ab avec support SSL) et/ou mod_deflate. Les fichiers .mak supportent aussi un choix plus large de distributions de chaînes d'outils C++, comme Visual Studio Express.

Vous devez tout d'abord compiler tous les projets afin de créer toutes les cibles dynamiques auto-générées, de façon à ce que les dépendances puissent être interprétées correctement. Compilez l'ensemble du projet depuis l'IDE Visual Studio 6.0 (98), en utilisant la cible BuildAll, puis utilisez le menu de projet Export pour tous les makefiles (en cochant "with dependencies"). Utilisez la commande suivante pour transformer les chemins absolus en chemins relatifs de façon à ce que la compilation puisse s'effectuer depuis n'importe quelle position dans l'arborescence :

perl srclib\apr\build\fixwin32mak.pl

Vous devez exécuter cette commande depuis la racine de l'arborescence des sources de httpd. Tout fichier projet .mak et .dep du répertoire courant et de ses sous-répertoires sera corrigé, et les repères de temps ajustés en fonction des .dsp.

Vérifiez toujours le SDK de la plate-forme ou autres chemins fichiers locaux, spécifiques à la machine dans les fichiers .mak et .dep générés. Le répertoire DevStudio\Common\MSDev98\bin\ (VC6) contient un fichier sysincl.dat qui énumère toutes les exceptions. Mettez à jour ce fichier (en particulier les chemins avec slashes et anti-slashes, tels que sys/time.h et sys\time.h) de façon à ignorer ces nouvelles dépendances. Inclure les chemins d'installation locale dans un fichier .mak distribué fera échouer la compilation.

Si vous soumettez un patch qui modifie les fichiers projet, nous devons valider la modification de ces fichiers projet au format Visual Studio 6.0. Les modifications doivent êtres simples, avec un minimum de drapeaux de compilation et d'édition de liens qui pourront être reconnus par tous les environnements Visual Studio.

Installation

Une fois compilé, Apache doit être installé dans le répertoire racine du serveur. La valeur par défaut est le répertoire \Apache2, sur le même disque.

Pour compiler et installer automatiquement tous les fichiers dans le répertoire rep désiré, utilisez une des commandes nmake suivantes :

nmake /f Makefile.win installr INSTDIR=dir
nmake /f Makefile.win installd INSTDIR=dir

L'argument rep de INSTDIR permet de spécifier le répertoire d'installation ; il peut être omis si Apache doit être installé dans \Apache22 (du lecteur de disque courant.

Avertissement à propos de la compilation d'Apache à partir de l'arborescence de développement

Notez que seuls les fichiers .dsp sont maintenus d'une distribution release à l'autre. Les fichiers .mak ne sont PAS régénérés, suite à l'énorme perte de temps des relecteurs . Vous ne pouvez donc pas utiliser les commandes NMAKE ci-dessus pour compiler des fichiers de projet .dsp révisés si vous n'exporter pas ensuite vous-même tous les fichiers .mak du projet. Ceci n'est pas nécessaire si vous effectuez la compilation depuis l'environnement Microsoft Developer Studio.

Compilation de httpd avec cmake

La documentation principale pour ce mécanisme de compilation se trouve dans le fichier README.cmake situé dans l'arborescence des sources. Consultez ce fichier pour des instructions détaillées.

Pour compiler httpd avec cmake, vous devez compiler APR et APR-util séparément. Consultez les fichiers README.cmake de ces projets pour obtenir des instructions.

Les principales limitations de la compilation basée sur cmake sont héritées du projet APR-util et sont énumérées ci-dessous à cause de leur impact sur httpd :

  • Il n'est pas possible de compiler le projet APR-iconv avec cmake, et la compilation de APR-util ne peut pas utiliser de projet APR-iconv précompilé. A cause de cela, il n'est pas possible d'utiliser mod_charset_lite et probablement d'autres modules tiers.
  • La compilation du sous-projet APR-util avec cmake ne supporte pas la plupart des bibliothèques optionnelles DBM et DBD utilisées par les fichiers projet Visual Studio inclus. Cela limite les serveurs de bases de données d'arrière-plan supportés par de nombreux modules tiers ou inclus.


Using Apache With RPM Based Systems (Redhat / CentOS / Fedora) - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

Using Apache With RPM Based Systems (Redhat / CentOS / Fedora)

While many distributions make Apache httpd available as operating system supported packages, it can sometimes be desirable to install and use the canonical version of Apache httpd on these systems, replacing the natively provided versions of the packages.

While the Apache httpd project does not currently create binary RPMs for the various distributions out there, it is easy to build your own binary RPMs from the canonical Apache httpd tarball.

This document explains how to build, install, configure and run Apache httpd 2.4 under Unix systems supporting the RPM packaging format.

Creating a Source RPM

The Apache httpd source tarball can be converted into an SRPM as follows:

rpmbuild -ts httpd-2.4.x.tar.bz2

Building RPMs

RPMs can be built directly from the Apache httpd source tarballs using the following command:

rpmbuild -tb httpd-2.4.x.tar.bz2

Corresponding "-devel" packages will be required to be installed on your build system prior to building the RPMs, the rpmbuild command will automatically calculate what RPMs are required and will list any dependencies that are missing on your system. These "-devel" packages will not be required after the build is completed, and can be safely removed.

If successful, the following RPMs will be created:

httpd-2.4.x-1.i686.rpm
The core server and basic module set.
httpd-debuginfo-2.4.x-1.i686.rpm
Debugging symbols for the server and all modules.
httpd-devel-2.4.x-1.i686.rpm
Headers and development files for the server.
httpd-manual-2.4.x-1.i686.rpm
The webserver manual.
httpd-tools-2.4.x-1.i686.rpm
Supporting tools for the webserver.
mod_authnz_ldap-2.4.x-1.i686.rpm
mod_ldap and mod_authnz_ldap, with corresponding dependency on openldap.
mod_lua-2.4.x-1.i686.rpm
mod_lua module, with corresponding dependency on lua.
mod_proxy_html-2.4.x-1.i686.rpm
mod_proxy_html module, with corresponding dependency on libxml2.
mod_socache_dc-2.4.x-1.i686.rpm
mod_socache_dc module, with corresponding dependency on distcache.
mod_ssl-2.4.x-1.i686.rpm
mod_ssl module, with corresponding dependency on openssl.

Installing the Server

The httpd RPM is the only RPM necessary to get a basic server to run. Install it as follows:

rpm -U httpd-2.4.x-1.i686.rpm

Self contained modules are included with the server. Modules that depend on external libraries are provided as separate RPMs to install if needed.

Configuring the Default Instance of Apache httpd

The default configuration for the server is installed by default beneath the /etc/httpd directory, with logs written by default to /var/log/httpd. The environment for the webserver is set by default within the optional /etc/sysconfig/httpd file.

Start the server as follows:

service httpd restart

Configuring Additional Instances of Apache httpd on the Same Machine

It is possible to configure additional instances of the Apache httpd server running independently alongside each other on the same machine. These instances can have independent configurations, and can potentially run as separate users if so configured.

This was done by making the httpd startup script aware of its own name. This name is then used to find the environment file for the server, and in turn, the server root of the server instance.

To create an additional instance called httpd-additional, follow these steps:

  • Create a symbolic link to the startup script for the additional server:

    ln -s /etc/rc.d/init.d/httpd /etc/rc.d/init.d/httpd-additional
    chkconfig --add httpd-additional

  • Create an environment file for the server, using the /etc/sysconfig/httpd file as a template:

    # template from httpd
    cp /etc/sysconfig/httpd /etc/sysconfig/httpd-additional

    # blank template
    touch /etc/sysconfig/httpd-additional

    Edit /etc/sysconfig/httpd-additional and pass the server root of the new server instance within the OPTIONS environment variable.

    OPTIONS="-d /etc/httpd-additional -f conf/httpd-additional.conf"

  • Edit the server configuration file /etc/httpd-additional/conf/httpd-additional.conf to ensure the correct ports and paths are configured.
  • Start the server as follows:

    service httpd-additional restart

  • Repeat this process as required for each server instance.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Utilisation d'Apache avec Novell NetWare - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Notes spécifiques à un système

Utilisation d'Apache avec Novell NetWare

Ce document explique l'installation, la configuration et le lancement d'Apache 2.0 sous Novell NetWare 6.0 et les versions ultérieures. Si vous trouvez une bogue, ou voulez tout simplement contribuer de quelque manière que ce soit, utilisez s'il vous plait notre page des rapports de bogues.

La page des rapports de bogues et la liste de diffusion dev-httpd ne doivent pas être utilisées pour poser des questions à propos de la configuration ou du lancement d'Apache. Avant de soumettre un rapport de bogue ou une question, consultez ce document, la FAQ ou tout autre sujet de la documentation en rapport avec votre problème. Si vous n'avez toujours pas résolu votre problème, postez votre question dans le newsgroup novell.devsup.webserver, où de nombreux utilisateurs d'Apache sont prêts à répondre à toutes les nouvelles et obscures questions à propos de l'utilisation d'Apache sous Netware.

Dans la majeure partie de ce document, vous êtes sensé avoir installé Apache à partir d'une distribution binaire. Si vous voulez compiler Apache vous-même (par exemple pour aider au développement, ou pour rechercher des bogues), reportez-vous à la section traitant de la Compilation d'Apache pour Netware ci-dessous.

Prérequis

Apache 2.0 nécessite NetWare 6.0 service pack 3 et supérieurs pour fonctionner. Si vous utilisez un service pack antérieur à SP3, vous devez installer les dernières Bibliothèques Netware pour C (LibC).

Vous trouverez les service packs Netware ici.

Apache 2.0 pour NetWare peut aussi fonctionner dans un environnement NetWare 5.1, à partir du moment où le dernier service pack ou la dernière version des Bibliothèques Netware pour C (LibC) ont été installés. ATTENTION : Apache 2.0 pour NetWare n'a pas été testé dans cet environnement car il n'a pas été conçu pour ce dernier.

Téléchargement d'Apache pour NetWare

Les informations à propos de la dernière version d'Apache sont disponibles sur le site web d'Apache à http://www.apache.org/. Vous y trouverez la version courante, des versions alpha ou bêta-test plus récentes, ainsi que des sites miroirs et des sites FTP anonymes. Les distributions binaires des dernières versions d'Apache 2.0 pour NetWare sont disponibles ici.

Installation d'Apache pour NetWare

Il n'existe pas actuellement de programme d'installation d'Apache pour Netware. Si vous installez Apache 2.0 pour NetWare à partir des sources, vous devrez copier les fichiers sur le serveur manuellement.

Suivez ces instructions pour installer Apache sous Netware à partir de la distribution binaire (en supposant que vous effectuez l'installation dans sys:/apache2) :

  • Décompressez le fichier binaire téléchargé à la racine du volume SYS: (vous pouvez cependant l'installer dans tout volume)
  • Editez le fichier httpd.conf et définissez les directives ServerRoot et ServerName avec les valeurs correctes des chemins de fichiers qui correspondent à la configuration de votre serveur.
  • Ajoutez SYS:/APACHE2 au chemin de recherche, par une commande du style :

    SEARCH ADD SYS:\APACHE2

Suivez ces instructions pour installer Apache pour Netware manuellement à partir de votre propre répertoire de sources (en supposant que vous effectuez l'installation dans sys:/apache2) :

  • Créez un répertoire que vous appellerez Apache2 dans un volume Netware.
  • Copiez APACHE2.NLM, APRLIB.NLM dans SYS:/APACHE2.
  • Créez un répertoire que vous appellerez BIN dans SYS:/APACHE2.
  • Copiez HTDIGEST.NLM, HTPASSWD.NLM, HTDBM.NLM, LOGRES.NLM, ROTLOGS.NLM dans SYS:/APACHE2/BIN.
  • Créez un répertoire que vous appellerez CONF dans SYS:/APACHE2.
  • Copiez le fichier HTTPD-STD.CONF dans le répertoire SYS:/APACHE2/CONF et renommez-le en HTTPD.CONF.
  • Copiez les fichiers MIME.TYPES, CHARSET.CONV et MAGIC dans le répertoire SYS:/APACHE2/CONF.
  • Copiez tous les fichiers et sous-répertoires de \HTTPD-2.0\DOCS\ICONS dans SYS:/APACHE2/ICONS.
  • Copiez tous les fichiers et sous-répertoires de \HTTPD-2.0\DOCS\MANUAL dans SYS:/APACHE2/MANUAL.
  • Copiez tous les fichiers et sous-répertoires de \HTTPD-2.0\DOCS\ERROR dans SYS:/APACHE2/ERROR.
  • Copiez tous les fichiers et sous-répertoires de \HTTPD-2.0\DOCS\DOCROOT dans SYS:/APACHE2/HTDOCS.
  • Créez le répertoire SYS:/APACHE2/LOGS sur le serveur.
  • Créez le répertoire SYS:/APACHE2/CGI-BIN sur le serveur.
  • Créez le répertoire SYS:/APACHE2/MODULES et copiez tous les modules nlm dans le répertoire modules.
  • Editez le fichier HTTPD.CONF, et recherchez toutes les marques @@Value@@ afin de les remplacer par les valeurs appropriées.
  • Ajoutez SYS:/APACHE2 au chemin de recherche, par une commande du style :

    SEARCH ADD SYS:\APACHE2

    .

Outre le volume par défaut SYS, Apache peut être installé dans tout autre volume.

Au cours du processus d'installation, l'ajout du mot-clé "install" à la ligne de commande du makefile va provoquer la construction d'une distribution complète sous forme d'un paquetage dans le sous-répertoire DIST. Vous pouvez simplement installer Apache en copiant la distribution créée précédemment à la racine d'un volume Netware (voir Compilation d'Apache pour NetWare ci-dessous).

Exécuter Apache pour NetWare

Pour démarrer Apache, tapez simplement apache dans la console. Ceci aura pour effet de charger Apache dans l'espace d'adressage du système d'exploitation. Si vous préférez charger Apache dans un espace d'adressage protégé, vous pouvez spécifier cet espace d'adressage à l'aide de l'instruction de chargement suivante :

load address space = apache2 apache2

Cette instruction va charger Apache dans un espace d'adressage appelé apache2. Il est possible d'exécuter plusieurs instances simultanées d'Apache sous Netware, en chargeant chacune d'entre elles dans son propre espace d'adressage protégé.

Une fois démarré, Apache écoute le port 80 (à moins que vous n'ayez modifié la directive Listen dans les fichiers de configuration). Pour vous connecter au serveur et afficher la page par défaut, lancez un navigateur et entrez le nom du serveur ou son adresse IP. Vous devriez voir une page de bienvenue, et un lien vers le manuel Apache. Si rien ne se produit, ou si vous obtenez un message d'erreur, consultez le fichier error_log dans le répertoire logs.

Lorsque votre installation de base fonctionne, vous devez la configurer correctement en éditant les fichiers du répertoire conf.

Pour arrêter une instance d'Apache s'exécutant dans l'espace d'adressage du système d'exploitation, entrez simplement dans la console :

unload apache2

ou

apache2 shutdown

Si Apache s'exécute dans un espace d'adressage protégé, spécifiez cet espace d'adressage dans l'instruction d'arrêt :

unload address space = apache2 apache2

Lorsqu'on travaille avec Apache, il est important de savoir comment il trouve ses fichiers de configuration. Vous pouvez spécifier un fichier de configuration sur la ligne de commande de deux manières :

  • -f spécifie un chemin vers un fichier de configuration particulier

apache2 -f "vol:/nom-serveur/conf/fich-conf.conf"

apache -f test/test.conf

Dans ces cas, la directive ServerRoot doit être correctement définie dans le fichier de configuration.

Si vous ne spécifiez pas de nom de fichier de configuration avec l'option -f, Apache utilisera le nom de fichier codé en dur dans le serveur, en général conf/httpd.conf. L'invocation d'Apache avec l'option -V indiquera ce nom comme valeur de l'étiquette SERVER_CONFIG_FILE. Apache va ensuite déterminer son ServerRoot en effectuant les tests suivants, dans cet ordre

  • Une directive ServerRoot via une option -C switch.
  • L'option de ligne de commande -d.
  • Le contenu du répertoire courant.
  • La racine du répertoire d'installation codée en dur dans le serveur.

La racine du répertoire d'installation codée en dur dans le serveur est en général sys:/apache2. L'invocation d'Apache avec l'option -V indiquera ce chemin comme valeur de l'étiquette HTTPD_ROOT.

Apache 2.0 pour Netware comporte un jeu d'options de ligne de commande permettant d'afficher ou de modifier certaines caractéristiques de l'instance du serveur web en cours d'exécution. Ces options ne sont disponibles que lorsqu'Apache est en cours d'exécution. Chacune de ces options doit être précédée du mot-clé APACHE2.

RESTART
Demande à Apache d'arrêter tout worker thread en cours d'exécution lorsqu'il devient inactif, de recharger le fichier de configuration, et de redémarrer chaque worker thread en fonction de la nouvelle configuration.
VERSION
Affiche des informations à propos de la version de l'instance d'Apache en cours d'exécution.
MODULES
Affiche la liste des modules chargés (intégrés et externes).
DIRECTIVES
Affiche la liste des directives disponibles.
SETTINGS
Active ou désactive l'affichage du statut des threads sur la console. En cas d'activation, l'état de chaque thread en cours d'exécution s'affiche sur l'écran de la console Apache.
SHUTDOWN
Arrête l'instance du serveur web Apache en cours d'exécution.
HELP
Décrit chacune des options disponibles au cours de l'exécution d'Apache.

Par défaut, ces options sont passées à l'instance d'apache s'exécutant dans l'espace d'adressage du système d'exploitation. Pour passer une option à une instance d'Apache spécifique s'exécutant dans un espace d'adressage protégé, ajouter le paramètre -p suivi du nom de l'espace d'adressage. Pour plus d'informations, tapez "apache2 Help" sur la ligne de commande.

Configuration d'Apache pour NetWare

Apache lit en général ses fichiers de configuration dans le répertoire conf. Ces fichiers sont les mêmes que ceux de la version Unix, mais quelques directives sont différentes sous Netware. Voir la Documentation Apache pour l'ensemble des directives disponibles.

Les principales différences propres à Apache pour NetWare sont :

  • Comme Apache pour Netware est une application multithread, elle n'utilise pas de processus séparé pour chaque requête, comme c'est le cas pour certaines implémentations sous Unix. Il n'y a que des threads en cours d'exécution : un thread parent, et plusieurs threads enfants ou worker qui traitent les requêtes.

    En conséquence, les directives de gestion des "processus" sont différentes :

    MaxConnectionsPerChild - comme sous Unix, cette directive contrôle le nombre maximum de connexions qu'un worker thread peut traiter avant de s'arrêter. Avec la valeur par défaut MaxConnectionsPerChild 0, le thread va pouvoir traiter un nombre illimité de requêtes. Cette valeur est recommandée sous Netware, à moins que vous n'ayez des raisons particulières de la modifier.

    StartThreads - Cette directive indique au serveur le nombre de threads qu'il doit lancer au démarrage. Il est recommandé de conserver la valeur par défaut StartThreads 50.

    MinSpareThreads - Cette directive indique au serveur le nombre de worker threads additionnels qu'il doit lancer si le nombre de threads inactifs tombe en dessous de cette valeur. Il est recommandé de conserver la valeur par défaut MinSpareThreads 10.

    MaxSpareThreads - Cette directive indique au serveur qu'il doit commencer à arrêter des worker threads si le nombre de threads inactifs passe au dessus de cette valeur. Il est recommandé de conserver la valeur par défaut MaxSpareThreads 100.

    MaxThreads - Cette directive impose un nombre maximum de worker threads. Il est recommandé de conserver la valeur par défaut ThreadsPerChild 250.

    ThreadStackSize - Cette directive indique au serveur la taille de la pile à utiliser pour un worker thread individuel. Il est recommandé de conserver la valeur par défaut ThreadStackSize 65536.

  • Les directives qui acceptent des noms de fichiers comme arguments ne doivent pas utiliser des noms de fichiers Unix, mais des noms de fichiers Netware. Cependant, comme Apache utilise des noms de style Unix en interne, on doit utiliser des slashes et non des antislashes. Il est recommandé de préfixer tous les chemins de fichiers racines par un nom de volume. Si ce dernier est omis, Apache supposera que le volume est SYS:, ce qui n'est pas forcément correct.

  • Apache pour Netware a la possibilité de charger des modules en cours d'exécution, sans avoir à recompiler le serveur. Si Apache est compilé avec les options par défaut, il va installer de nombreux modules optionnels dans le répertoire \Apache2\modules. Pour les activer, ou en activer d'autres, on doit utiliser la directive LoadModule. Par exemple, pour activer le module status, ajoutez la ligne suivante :

    LoadModule status_module modules/status.nlm

    Des informations à propos de la création de modules chargeables sont aussi disponibles.

Autres directives spécifiques à Netware :

  • CGIMapExtension - Cette directive associe une extension de fichier CGI à un interpréteur de script.
  • SecureListen - Cette directive active le chiffrement SSL pour un port spécifique.
  • NWSSLTrustedCerts - Cette directive permet d'ajouter des certificats de confiance pouvant être utilisés pour créer des connexions sécurisées vers des serveurs mandataires.
  • NWSSLUpgradeable - Cette directive permet de faire passer en SSL une connexion initialisée sur les adresse IP et Port spécifiés.

Compilation d'Apache pour NetWare

La compilation d'Apache nécessite MetroWerks CodeWarrior 6.x ou supérieur. Une fois compilé, Apache peut être installé à la racine de tout volume Netware. Le répertoire d'installation par défaut est sys:/Apache2.

Avant de démarrer Apache, vous devez remplir le répertoire conf. Copiez le fichier HTTPD-STD.CONF depuis le répertoire conf de la distribution et renommez-le en HTTPD.CONF. Editez le fichier HTTPD.CONF en recherchant les repères @@Value@@, et remplacez ces derniers par la valeur appropriée. Copiez de même les fichiers conf/magic et conf/mime.types. Vous pouvez aussi construire une distribution complète en ajoutant le mot-clé install lors de l'invocation des makefiles.

Prérequis :

Les outils de développement suivants sont nécessaires pour la compilation d'Apache pour Netware :

  • Metrowerks CodeWarrior 6.0 ou supérieur avec le NetWare PDK 3.0 ou supérieur.
  • Les Bibliothèques Netware pour C (LibC)
  • Les Bibliothèques LDAP pour C
  • Le Code source de la bibliothèque de compression ZLIB
  • L'utilitaire AWK (awk, gawk ou similaire). AWK peut être téléchargé à http://developer.novell.com/ndk/apache.htm. L'utilitaire doit se trouver dans votre chemin windows et avoir pour nom awk.exe.
  • Pour utiliser les makefiles, vous devez disposer de GNU make version 3.78.1 (GMake) disponible à http://developer.novell.com/ndk/apache.htm.

Compiler Apache en utilisant les makefiles Netware :

  • Définissez la variable d'environnement NOVELLLIBC avec le chemin des bibliothèques Netware pour C SDK ; par exemple :

    Set NOVELLLIBC=c:\novell\ndk\libc

  • Définissez la variable d'environnement METROWERKS avec le chemin de votre compilateur Metrowerks CodeWarrior ; par exemple :

    Set METROWERKS=C:\Program Files\Metrowerks\CodeWarrior

    . Si vous l'avez installé dans le répertoire par défaut C:\Program Files\Metrowerks\CodeWarrior, vous n'avez pas besoin de définir cette variable.
  • Définissez la variable d'environnement LDAPSDK avec le chemin des bibliothèques LDAP pour C ; par exemple :

    Set LDAPSDK=c:\Novell\NDK\cldapsdk\NetWare\libc

  • Définissez la variable d'environnement ZLIBSDK avec le chemin du code source de la bibliothèque Zlib ; par exemple :

    Set ZLIBSDK=D:\NOVELL\zlib

  • Définissez la variable d'environnement PCRESDK avec le chemin d'installation du code source de la bibliothèque PCRE ; par exemple :

    Set PCRESDK=D:\NOVELL\pcre

  • Définissez la variable d'environnement AP_WORK avec le chemin du code source de httpd.

    Set AP_WORK=D:\httpd-2.0.x

  • Définissez la variable d'environnement APR_WORK avec le chemin du code source d'apr ; en général \httpd\srclib\apr, mais le projet APR peut se trouver en dehors de la structure des répertoires de httpd.

    Set APR_WORK=D:\apr-1.x.x

  • Définissez la variable d'environnement APU_WORK avec le chemin du code source d'apr-util ; en général \httpd\srclib\apr-util, mais le projet APR-UTIL peut se trouver en dehors de la structure des répertoires de httpd.

    Set APU_WORK=D:\apr-util-1.x.x

  • Vérifiez que les chemins des utilitaires AWK et GNU make (gmake.exe) ont bien été inclus dans la variable d'environnement système PATH.
  • Téléchargez le code source et décompressez-le dans un répertoire de votre choix sur votre station de travail.
  • Positionnez-vous dans le répertoire \httpd-2.0 et compilez les utilitaires précompilés à l'aide de la commande "gmake -f nwgnumakefile prebuild". Cette cible va créer le répertoire \httpd-2.0\nwprebuild, et y copier tous les utilitaires nécessaires au franchissement des étapes suivantes de la compilation.
  • Copiez les fichiers \httpd-2.0\nwprebuild\GENCHARS.nlm et \httpd-2.0\nwprebuild\DFTABLES.nlm vers le volume SYS: d'un serveur Netware et exécutez-les à l'aide des commandes suivantes :

    SYS:\genchars > sys:\test_char.h
    SYS:\dftables sys:\chartables.c

  • Copiez les fichiers test_char.h et chartables.c vers le répertoire \httpd-2.0\os\netware de la machine où s'effectue la compilation.
  • Positionnez-vous dans le répertoire \httpd-2.0 et compilez Apache à l'aide de la commande "gmake -f nwgnumakefile". Vous pouvez créer un répertoire pour la distribution en ajoutant le paramètre install à la commande ; par exemple :

    gmake -f nwgnumakefile install

Options de make supplémentaires

  • gmake -f nwgnumakefile

    Compile les versions de distribution de tous les binaires et les copie dans un répertoire \release.

  • gmake -f nwgnumakefile DEBUG=1

    Compile les versions de débogage de tous les binaires et les copie dans un répertoire \debug.

  • gmake -f nwgnumakefile install

    Crée une distribution complète d'Apache avec les binaires, la documentation et les fichiers support dans un répertoire \dist\Apache2.

  • gmake -f nwgnumakefile prebuild

    Compile tous les utilitaires précompilés et les copie dans le répertoire \nwprebuild.

  • gmake -f nwgnumakefile installdev

    Même effet que l'option install, mais en plus, les répertoires \lib et \include sont créés dans le répertoire de destination, et les en-têtes et fichiers d'import y sont copiés.

  • gmake -f nwgnumakefile clean

    Supprime tous les fichiers objets et les binaires de la zone de compilation \release.o, ou \debug.o si DEBUG a été défini.

  • gmake -f nwgnumakefile clobber_all

    Même effet que clean, mais en plus, le répertoire de la distribution est supprimé s'il existe.

Variables d'environnement supplémentaires

  • Pour compiler tous les modules expérimentaux, définissez la variable d'environnement EXPERIMENTAL :

    Set EXPERIMENTAL=1

  • Pour compiler Apache en utilisant les sockets de style BSD standard, plutôt que Winsock, définissez la variable d'environnement USE_STDSOCKETS :

    Set USE_STDSOCKETS=1

Compilation de mod_ssl pour la plate-forme Netware

Pour fournir les services SSL, Apache pour Netware utilise par défaut le module intégré mod_nw_ssl. Ce module ne fournit que les services SSL implémentés par le système d'exploitation Netware lui-même pour gérer tous les chiffrements pour un port donné. Cependant, on peut aussi utiliser mod_ssl de la même manière que sur les autres plate-formes.

Afin de pouvoir compiler mod_ssl pour la plate-forme Netware, les bibliothèques OpenSSL doivent être disponibles. Elles peuvent être installées de la manière suivante :

  • Téléchargez la dernière distribution du code source d'OpenSSL 0.9.8 depuis la page OpenSSL Source (les versions 0.9.7 doivent être patchées, et ne sont donc pas recommandées).
  • Editez le fichier NetWare/set_env.bat, et effectuez toutes modifications nécessaires des chemins des outils et utilitaires en fonction de votre environnement de développement.
  • Exécutez les scripts suivants depuis la racine du répertoire des sources d'OpenSSL :

    Netware\set_env netware-libc
    Netware\build netware-libc

    Pour des raisons de performances, vous devez activer la compilation avec le code ASM. Télécharger NASM depuis le site SF. Configurez ensuite OpenSSL pour utiliser le code ASM :

    Netware\build netware-libc nw-nasm enable-mdc2 enable-md5

    Attention : n'utilisez pas l'Assembleur CodeWarrior - il produit un code de mauvaise qualité !
  • Avant de compiler Apache, définissez la variable d'environnement OSSLSDK avec le chemin absolu de la racine du répertoire du code source d'openssl, et définissez WITH_MOD_SSL à 1.

    Set OSSLSDK=d:\openssl-0.9.8x
    Set WITH_MOD_SSL=1


Mise en oeuvre d'un serveur Web hautes performances sous HPUX - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Notes spécifiques aux plates-formes

Mise en oeuvre d'un serveur Web hautes performances sous HPUX

Date: Wed, 05 Nov 1997 16:59:34 -0800
From: Rick Jones <raj@cup.hp.com>
Reply-To: raj@cup.hp.com
Organization: Network Performance
Subject: HP-UX tuning tips

Traduction du corps du message cité ci-dessus :

Voici quelques conseils de personnalisation pour HPUX à ajouter à la page de personnalisation.

Pour HP-UX 9.X: mettre à jour vers la version 10.20
Pour HP-UX 10.[00|01|10]: mettre à jour vers la version 10.20

Pour HP-UX 10.20:

Installez le dernier patch cumulatif à propos du transport ARPA. Ceci va vous permettre de configurer la taille de la table de hashage de recherche de connexion TCP. La valeur par défaut est 256 conteneurs et doit être une puissance de deux. À cet effet, utilisez adb pour modifier l'image *disque* du noyau. Le nom de la variable est tcp_hash_size. Notez qu'il est impératif d'utiliser "W" pour spécifier une quantité sur 32 bits, et non "w" qui indique une valeur sur 16 bits, lors de la modification de l'image disque car la variable tcp_hash_size est une quantité sur 32 bits.

Comment déterminer cette valeur ? Examinez la sortie de ftp://ftp.cup.hp.com/dist/networking/tools/connhist, et comptez le nombre total de connexions TCP existant sur le système. Il est en général souhaitable que ce nombre divisé par la taille de la table de hashage soit raisonnablement petit, disons inférieur à 10. Les administrateurs peuvent consulter le document SPECweb96 de HP pour quelques réglages courants. On peut les trouver à http://www.specbench.org/. Si un système HP-UX traite 1000 connexions SPECweb96 par seconde, une valeur de temps TIME_WAIT de 60 secondes permettrait le suivi de 60000 connexions TCP.

Les administrateurs peuvent tester la profondeur de leur file d'attente d'écoute avec ftp://ftp.cup.hp.com/dist/networking/misc/listenq.

Si Apache s'exécute sur un système à base de PA-8000, il est conseillé de modifier l'exécutable Apache avec la commande chatr afin d'utiliser une page de grande taille. La commande sera du style "chatr +pi L <BINARY>". Le GID de l'exécutable en cours de fonctionnement doit posséder le privilège MLOCK. Pour assigner ce privilège MLOCK, consultez Setprivgrp(1m). La modification peut être validée en exécutant Glance et en examinant les portions de mémoire du/des serveur(s) afin de s'assurer qu'elles montrent une fraction non triviale du segment de texte verrouillé.

Si Apache s'exécute sur un système MP (multi-processeurs), il est conseillé d'écrire un petit programme qui utilise mpctl() et permettant d'associer les processus aux processeurs. Un simple algorithme pid % numcpu suffira probablement. Cette modification peut aussi être ajoutée dans le code source.

Si l'administrateur s'intéresse au nombre de connexions FIN_WAIT_2, il peut utiliser nettune pour diminuer la valeur de tcp_keepstart. Il devra cependant être prudent - surtout ne pas diminuer cette valeur en dessous de, disons deux à quatre minutes. Si tcp_hash_size a été défini, il est probablement approprié de laisser les connexions FIN_WAIT_2 prendre plus de temps à expirer (peut-être même la valeur par défaut de deux heures) - elles n'auront en général pas un grand impact sur les performances.

On peut ajouter d'autres choses au code de base, mais elles feront peut-être l'objet d'un autre email. N'hésitez pas à m'envoyer un message si vous êtes intéressé.

sincèrement ,

rick jones

http://www.netperf.org/netperf/


The Apache EBCDIC Port - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Platform Specific Notes

The Apache EBCDIC Port

Warning: This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

Overview of the Apache EBCDIC Port

Version 1.3 of the Apache HTTP Server was the first version which included a port to a (non-ASCII) mainframe machine which uses the EBCDIC character set as its native codeset.

(It is the SIEMENS family of mainframes running the BS2000/OSD operating system. This mainframe OS nowadays features a SVR4-derived POSIX subsystem).

The port was started initially to

  • prove the feasibility of porting the Apache HTTP server to this platform
  • find a "worthy and capable" successor for the venerable CERN-3.0 daemon (which was ported a couple of years ago), and to
  • prove that Apache's preforking process model can on this platform easily outperform the accept-fork-serve model used by CERN by a factor of 5 or more.

This document serves as a rationale to describe some of the design decisions of the port to this machine.

Design Goals

One objective of the EBCDIC port was to maintain enough backwards compatibility with the (EBCDIC) CERN server to make the transition to the new server attractive and easy. This required the addition of a configurable method to define whether a HTML document was stored in ASCII (the only format accepted by the old server) or in EBCDIC (the native document format in the POSIX subsystem, and therefore the only realistic format in which the other POSIX tools like grep or sed could operate on the documents). The current solution to this is a "pseudo-MIME-format" which is intercepted and interpreted by the Apache server (see below). Future versions might solve the problem by defining an "ebcdic-handler" for all documents which must be converted.

Technical Solution

Since all Apache input and output is based upon the BUFF data type and its methods, the easiest solution was to add the conversion to the BUFF handling routines. The conversion must be settable at any time, so a BUFF flag was added which defines whether a BUFF object has currently enabled conversion or not. This flag is modified at several points in the HTTP protocol:

  • set before a request is received (because the request and the request header lines are always in ASCII format)
  • set/unset when the request body is received - depending on the content type of the request body (because the request body may contain ASCII text or a binary file)
  • set before a reply header is sent (because the response header lines are always in ASCII format)
  • set/unset when the response body is sent - depending on the content type of the response body (because the response body may contain text or a binary file)

Porting Notes

  1. The relevant changes in the source are #ifdef'ed into two categories:

    #ifdef CHARSET_EBCDIC

    Code which is needed for any EBCDIC based machine. This includes character translations, differences in contiguity of the two character sets, flags which indicate which part of the HTTP protocol has to be converted and which part doesn't etc.

    #ifdef _OSD_POSIX

    Code which is needed for the SIEMENS BS2000/OSD mainframe platform only. This deals with include file differences and socket implementation topics which are only required on the BS2000/OSD platform.

  2. The possibility to translate between ASCII and EBCDIC at the socket level (on BS2000 POSIX, there is a socket option which supports this) was intentionally not chosen, because the byte stream at the HTTP protocol level consists of a mixture of protocol related strings and non-protocol related raw file data. HTTP protocol strings are always encoded in ASCII (the GET request, any Header: lines, the chunking information etc.) whereas the file transfer parts (i.e., GIF images, CGI output etc.) should usually be just "passed through" by the server. This separation between "protocol string" and "raw data" is reflected in the server code by functions like bgets() or rvputs() for strings, and functions like bwrite() for binary data. A global translation of everything would therefore be inadequate.

    (In the case of text files of course, provisions must be made so that EBCDIC documents are always served in ASCII)

  3. This port therefore features a built-in protocol level conversion for the server-internal strings (which the compiler translated to EBCDIC strings) and thus for all server-generated documents. The hard coded ASCII escapes \012 and \015 which are ubiquitous in the server code are an exception: they are already the binary encoding of the ASCII \n and \r and must not be converted to ASCII a second time. This exception is only relevant for server-generated strings; and external EBCDIC documents are not expected to contain ASCII newline characters.

  4. By examining the call hierarchy for the BUFF management routines, I added an "ebcdic/ascii conversion layer" which would be crossed on every puts/write/get/gets, and a conversion flag which allowed enabling/disabling the conversions on-the-fly. Usually, a document crosses this layer twice from its origin source (a file or CGI output) to its destination (the requesting client): file -> Apache, and Apache -> client.

    The server can now read the header lines of a CGI-script output in EBCDIC format, and then find out that the remainder of the script's output is in ASCII (like in the case of the output of a WWW Counter program: the document body contains a GIF image). All header processing is done in the native EBCDIC format; the server then determines, based on the type of document being served, whether the document body (except for the chunking information, of course) is in ASCII already or must be converted from EBCDIC.

  5. For Text documents (MIME types text/plain, text/html etc.), an implicit translation to ASCII can be used, or (if the users prefer to store some documents in raw ASCII form for faster serving, or because the files reside on a NFS-mounted directory tree) can be served without conversion.

    Example:

    to serve files with the suffix .ahtml as a raw ASCII text/html document without implicit conversion (and suffix .ascii as ASCII text/plain), use the directives:

    AddType text/x-ascii-html .ahtml
    AddType text/x-ascii-plain .ascii

    Similarly, any text/foo MIME type can be served as "raw ASCII" by configuring a MIME type "text/x-ascii-foo" for it using AddType.

  6. Non-text documents are always served "binary" without conversion. This seems to be the most sensible choice for, .e.g., GIF/ZIP/AU file types. This of course requires the user to copy them to the mainframe host using the "rcp -b" binary switch.

  7. Server parsed files are always assumed to be in native (i.e., EBCDIC) format as used on the machine, and are converted after processing.

  8. For CGI output, the CGI script determines whether a conversion is needed or not: by setting the appropriate Content-Type, text files can be converted, or GIF output can be passed through unmodified. An example for the latter case is the wwwcount program which we ported as well.

Document Storage Notes

Binary Files

All files with a Content-Type: which does not start with text/ are regarded as binary files by the server and are not subject to any conversion. Examples for binary files are GIF images, gzip-compressed files and the like.

When exchanging binary files between the mainframe host and a Unix machine or Windows PC, be sure to use the ftp "binary" (TYPE I) command, or use the rcp -b command from the mainframe host (the -b switch is not supported in unix rcp's).

Text Documents

The default assumption of the server is that Text Files (i.e., all files whose Content-Type: starts with text/) are stored in the native character set of the host, EBCDIC.

Server Side Included Documents

SSI documents must currently be stored in EBCDIC only. No provision is made to convert it from ASCII before processing.

Apache Modules' Status

Module | Status | Notes
core | + |
mod_access | + |
mod_actions | + |
mod_alias | + |
mod_asis | + |
mod_auth | + |
mod_authn_anon | + |
mod_authn_dbm | ? | with own libdb.a
mod_authz_dbm | ? | with own libdb.a
mod_autoindex | + |
mod_cern_meta | ? |
mod_cgi | + |
mod_digest | + |
mod_dir | + |
mod_so | - | no shared libs
mod_env | + |
mod_example | - | (test bed only)
mod_expires | + |
mod_headers | + |
mod_imagemap | + |
mod_include | + |
mod_info | + |
mod_log_agent | + |
mod_log_config | + |
mod_log_referer | + |
mod_mime | + |
mod_mime_magic | ? | not ported yet
mod_negotiation | + |
mod_proxy | + |
mod_rewrite | + | untested
mod_setenvif | + |
mod_speling | + |
mod_status | + |
mod_unique_id | + |
mod_userdir | + |
mod_usertrack | ? | untested

Third Party Modules' Status

Module | Status | Notes
JK (Formerly mod_jserv) | - | JAVA still being ported.
mod_php3 | + | mod_php3 runs fine, with LDAP and GD and FreeType libraries.
mod_put | ? | untested
mod_session | - | untested

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Le serveur et ses utilitaires - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Le serveur et ses utilitaires

Cette page documente tous les utilitaires inclus dans le serveur HTTP Apache.

Index

httpd
Le serveur de protocole de transfert hypertexte Apache
apachectl
L'interface de contrôle du serveur HTTP Apache
ab
L'outil de test de performances du serveur HTTP Apache
apxs
L'outil de gestion des extensions Apache
configure
Configuration de l'arborescence des sources
dbmmanage
Crée et met à jour les fichiers d'authentification utilisateurs au format DBM pour une authentification basique
fcgistarter
Lance un programme fastcgi
htcacheclean
Nettoie le cache sur disque
htdigest
Crée et met à jour les fichiers d'authentification pour une authentification sommaire
htdbm
Manipulation des bases de données DBM des mots de passe.
htpasswd
Crée et met à jour les fichiers d'authentification pour une authentification basique
httxt2dbm
Crée des fichiers dbm destinés à être utilisés avec RewriteMap
logresolve
Résolution des noms d'hôtes en adresses IP dans les fichiers de traces d'Apache
log_server_status
Journalisation périodique du statut du serveur
rotatelogs
Rotation des traces d'Apache sans devoir arrêter le serveur
split-logfile
Divise un journal pour plusieurs hôtes virtuels en journaux spécifiques à chaque hôte
suexec
Change d'utilisateur pour l'exécution de certains programmes


httpd - Le serveur HTTP d'Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

httpd - Le serveur HTTP d'Apache

httpd est le programme du serveur HTTP d'Apache. Il a été conçu pour fonctionner sous forme de processus démon indépendant. Lorsqu'il est utilisé ainsi, il va créer un jeu de processus enfants ou de threads qui traiteront les requêtes.

En général, httpd n'est pas invoqué directement, mais plutôt via apachectl sur les systèmes de style Unix ou en tant que service sous Windows NT, 2000 et XP et comme application de console sous Windows 9x et ME.

Voir aussi

  • Démarrer Apache httpd
  • Arrêter Apache httpd
  • Fichiers de configuration
  • Documentations spécifiques aux plates-formes
  • apachectl

Syntaxe

httpd [ -d racine-serveur ] [ -f config ] [ -C directive ] [ -c directive ] [ -D paramètre ] [ -e niveau ] [ -E fichier ] [ -k start|restart|graceful|stop|graceful-stop ] [ -h ] [ -l ] [ -L ] [ -S ] [ -t ] [ -v ] [ -V ] [ -X ] [ -M ] [ -T ]

Sur les systèmes Windows, les options additionnelles suivantes sont disponibles :

httpd [ -k install|config|uninstall ] [ -n nom ] [ -w ]

Options

-d racine-serveur
Définit la valeur initiale de la directive ServerRoot à racine-serveur. Cette valeur peut être écrasée par la directive ServerRoot du fichier de configuration. La valeur par défaut est /usr/local/apache2.
-f config
Utilise les directives du fichier config au démarrage. Si config ne commence pas par un '/', il est considéré comme relatif au chemin défini par la directive ServerRoot. La valeur par défaut est conf/httpd.conf.
-k start|restart|graceful|stop|graceful-stop
Permet de démarrer, redémarrer ou arrêter httpd. Voir Arrêter Apache httpd pour plus d'informations.
-C directive
Exécute la directive de configuration directive avant de lire les fichiers de configurations.
-c directive
Exécute la directive de configuration directive après avoir lu les fichiers de configurations.
-D paramètre
Définit un paramètre de configuration à utiliser dans les sections <IfDefine> des fichiers de configuration, ces dernières permettant d'exécuter ou non des commandes au démarrage ou au redémarrage du serveur. Sert aussi à définir certains paramètres de démarrage moins courants comme -DNO_DETACH (empêche le processus parent de lancer des processus enfants) et -DFOREGROUND (empêche le processus parent d'appeler setsid() et autres).
-e niveau
Définit la directive LogLevel à niveau pendant le démarrage du serveur. Ceci permet d'augmenter temporairement la verbosité des messages d'erreur afin de déterminer les problèmes de démarrage.
-E fichier
Envoie les messages d'erreur de démarrage vers le fichier fichier.
-h
Affiche un bref résumé des options de ligne de commande disponibles.
-l
Affiche la liste des modules compilés dans le le serveur. Ce paramètre n'affiche pas les modules chargés dynamiquement via la directive LoadModule.
-L
Affiche une liste des directives fournies par les modules statiques avec les arguments associés, ainsi que les contextes dans lesquels elles sont valides. Les directives fournies par les modules partagés (dynamiques) ne sont pas affichées).
-M
Affiche une liste des modules statiques et des modules chargés dynamiquement.
-S
Affiche la configuration telle qu'elle est issue de l'interprétation du fichier de configuration (actuellement, seule la configuration des serveurs virtuels est affichée).
-T (disponible depuis la version 2.3.8)
Empêche la vérification de la racine des documents (DocumentRoot) au démarrage/redémarrage.
-t
Exécute une vérification de syntaxe pour les fichiers de configuration seulement. Le programme se termine immédiatement après ces tests de vérification de syntaxe avec soit un code de retour de 0 (syntaxe OK), soit un code de retour différent de 0 (erreur de syntaxe). Si -D DUMP_VHOSTS est défini, les détails de la configuration des serveurs virtuels seront affichés. Si -D DUMP_MODULES est défini, tous les modules chargés seront affichés.
-v
Print the version of httpd, and then exit.
-V
Le programme affiche la version et les paramètres de compilation de httpd, puis se termine.
-X
Exécute httpd en mode debug. Un seul processus sera démarré, et le serveur ne rendra pas la main à la console.

Les arguments suivants ne sont disponibles que sur la plate-forme Windows :

-k install|config|uninstall
Respectivement : installe Apache httpd en tant que service Windows NT ; modifie les options de démarrage du service Apache httpd ; désinstalle le service Apache httpd.
-n nom
Le nom du service Apache httpd à actionner.
-w
Garde la console Windows ouverte en cas de problème de façon à ce que le message d'erreur puisse être lu.


ab - L'outil de test des performances du serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

ab - L'outil de test des performances du serveur HTTP Apache

ab est un utilitaire qui vous permet de tester les performances de votre serveur HTTP Apache. Il a été conçu pour vous donner une idée du degré de performances de votre installation d'Apache. Il vous permet en particulier de déterminer le nombre de réquêtes que votre installation d'Apache est capable de servir par seconde.

Voir aussi

  • httpd

Syntaxe

ab
    [ -A nom-utilisateur:mot-de-passe ]
    [ -b taille-tampon ]
    [ -B adresse-locale ]
    [ -c simultanéité ]
    [ -C nom-cookie=valeur ]
    [ -d ]
    [ -e fichier-csv ]
    [ -f protocole ]
    [ -g fichier-gnuplot ]
    [ -h ]
    [ -H en-tête-personnalisé ]
    [ -i ]
    [ -k ]
    [ -l ]
    [ -m HTTP-method ]
    [ -n requêtes ]
    [ -p fichier-POST ]
    [ -P
    nom-utilisateur-mandataire:mot-de-passe ]
    [ -q ]
    [ -r ]
    [ -s timeout ]
    [ -S ]
    [ -t limite-de-durée ]
    [ -T type-de-contenu ]
    [ -u fichier PUT ]
    [ -v verbosité]
    [ -V ]
    [ -w ]
    [ -x <table>-attributs ]
    [ -X mandataire[:port] ]
    [ -y <tr>-attributs ]
    [ -z <td>-attributs ]
    [ -Z algorithme-chiffrement ]
    [http[s]://]nom-serveur[:port]/chemin

Options

-A nom-utilisateur:mot-de-passe
Fournit le support d'une authentification de base vers le serveur. Les nom-utilisateur et mot-de-passe sont séparés par un seul caractère : et transmis sous forme codée base64. La chaîne est envoyée que le serveur en ait besoin ou non (qu'il ait renvoyé un code "401 authentication needed" ou non).
-b taille-tampon
Taille du tampon d'émission/réception TCP, en octets.
-B adresse-locale
Adresse à laquelle se rattacher lors des connexions sortantes.
-c simultanéité
Nombre de requêtes à effectuer simultanément. Par défaut, une seule requête est effectuée à la fois.
-C nom-cookie=valeur
Ajoute une ligne Cookie: à la requête. L'argument se présente en général sous la forme d'une paire nom=valeur. Ce champ peut être répété.
-d
N'affiche pas le "pourcentage servi dans la table XX [ms]". (support de l'héritage).
-e fichier-csv
Enregistre des valeurs séparées par des virgules (CSV) dans un fichier, indiquant pour chaque pourcentage (de 1% à 100 %), le temps (en millisecondes) mis pour servir ce pourcentage de requêtes. Ce fichier est en général plus utile qu'un fichier 'gnuplot', car les résultats sont déjà sous forme binaire.
-f protocole
Spécifie le protocole SSL/TLS (SSL2, SSL3, TLS1, TLS1.1, TLS1.2, or ALL). TLS1.1 et TLS1.2 sont supportés à partir de la version 2.4.4 du serveur HTTP Apache.
-g fichier-gnuplot
Enregistre toutes les valeurs mesurées dans un fichier 'gnuplot' ou TSV (valeurs séparées par des tabulations). Ce fichier peut être facilement importé dans des programmes comme Gnuplot, IDL, Mathematica, Igor ou même Excel. La première ligne du fichier contient les noms des valeurs.
-h
Affiche une aide à propos de l'utilisation du programme.
-H en-tête-personnalisé
Ajoute des en-têtes supplémentaires à la requête. L'argument se présente sous la forme d'une ligne d'en-tête valide, autrement dit une paire champ/valeur séparés par un caractère ':' (par exemple "Accept-Encoding: zip/zop;8bit").
-i
Effectue des requêtes HEAD plutôt que GET.
-k
Active la fonctionnalité des connexions HTTP persistantes (KeepAlive), c'est à dire effectue plusieurs requêtes au cours d'une seule session HTTP. Cette fonctionnalité est désactivée par défaut.
-l
Ne signale pas les erreurs si la taille de la réponse n'est pas constante. Cette option peut s'avérer utile pour les pages dynamiques. Disponible à partir de la version 2.4.7 du serveur HTTP Apache.
-m HTTP-method
Méthode HTTP personnalisée à utiliser pour les requêtes. Disponible à partir de la version 2.4.10 du serveur HTTP Apache.
-n requêtes
Nombre de requêtes à effectuer au cours du test de performances. Par défaut, une seule requête est effectuée, ce qui ne permet pas d'obtenir des résultats représentatifs.
-p fichier-POST
Fichier contenant les données pour les requêtes POST. Assurez-vous de spécifier aussi le paramètre -T.
-P nom-utilisateur-mandataire:mot-de-passe
Fournit les informations d'authentification basique pour un mandataire en-route. Les nom d'utilisateur et mot de passe sont séparés par un simple caractère : et envoyés sur le réseau codés en base64. La chaîne est envoyée, que le mandataire en ait besoin ou non (qu'il ait renvoyé un code "407 proxy authentication needed" ou non).
-q
Lorsque plus de 150 requêtes sont traitées, ab affiche la progression du traitement sur stderr tous les 10% du nombre total ou toutes les 100 requêtes. Le drapeau -q permet de supprimer ces messages.
-r
Ne s'arrête pas en cas d'erreur de réception du socket.
-s timeout
Temps maximum d'attente en secondes du socket avant de considérer le délai comme dépassé. La valeur par défaut est de 30 secondes. Disponible à partir de la version 2.4.4 du serveur HTTP Apache.
-S
N'affiche ni les valeurs de déviation standards et médianes, ni les messages d'erreur et d'avertissement lorsque les valeurs médianes et moyennes sont égales à une ou deux fois la valeur de déviation standard. Par défaut les valeurs mini/moyenne/maxi sont affichées (support de l'héritage).
-t limite-durée
Durée maximale en secondes du test de performances. Ceci implique un -n 50000 en interne. Utilisez cette option si vous souhaitez tester les performances du serveur pendant une durée fixée à l'avance. Par défaut, il n'y a pas de limite de durée.
-T type-contenu
Valeur de l'en-tête Content-type à utiliser pour les données POST/PUT, par exemple application/x-www-form-urlencoded. La valeur par défaut est text/plain.
-u fichier PUT
Fichier contenant des données PUT. Ne pas oublier de spécifier aussi -T.
-v verbosité
Définit le niveau de verbosité - les niveaux 4 et supérieurs permettent d'afficher des informations à propos des en-têtes, les niveaux 3 et supérieurs les codes de réponse (404, 200, etc...), et les niveaux 2 et supérieurs les messages d'avertissement et d'information.
-V
Affiche le numéro de version et s'arrête.
-w
Affiche les résultats dans des tables HTML. La table par défaut comporte deux colonnes sur fond blanc.
-x <table>-attributs
La chaîne à utiliser comme attributs pour <table>. Les attributs sont insérés <table ici >.
-X mandataire[:port]
Utilise un serveur mandataire pour les requêtes.
-y <tr>-attributs
La chaîne à utiliser comme attributs pour <tr>.
-z <td>-attributs
La chaîne à utiliser comme attributs pour <td>.
-Z algorithme-chiffrement
Spécifie l'algorithme de chiffrement SSL/TLS (Voir les algorithme de chiffrement openssl).

Sortie

Vous touverez dans ce qui suit la liste des valeurs retournées par ab :

Server Software
La valeur, si elle existe, de l'en-tête HTTP server renvoyée dans la première réponse réussie. Elle comporte tous les caractères de l'en-tête jusqu'à ce qu'un caractère de valeur décimale 32 soit rencontré (le plus souvent un espace ou une fin de ligne).
Server Hostname
Le nom DNS ou l'adresse IP fourni dans la ligne de commande.
Server Port
Le port auquel ab est connecté. Si la ligne de commande ne spécifie aucun port, le port par défaut sera 80 pour http et 443 pour https.
SSL/TLS Protocol
Les paramètres de protocole négociés entre le client et le serveur. Uniquement si SSL est utilisé.
Document Path
L'URI de la requête interprété à partir de la chaîne de la ligne de commande.
Document Length
Il s'agit de la taille en octets du premier document renvoyé avec succès. Si la taille du document est modifiée au cours du test, la réponse est considérée comme une erreur.
Concurrency Level
Le nombre de clients simultanés utilisés au cours du test.
Time taken for tests
Il s'agit du temps écoulé entre le moment de la première connexion au socket et la réception de la dernière réponse.
Complete requests
Le nombre de réponses reçues avec succès.
Failed requests
Le nombre de requêtes considérées comme erronées. Si ce nombre est différent de 0, une ligne supplémentaire indiquera le nombre de requêtes ayant échoué suite à un problème de connexion, de lecture, de taille de contenu erronée ou d'exceptions.
Write errors
Le nombre d'erreurs rencontrées en cours d'écriture (broken pipe).
Non-2xx responses
Le nombre de réponses dont le code était en dehors de la série 200. Si toutes les réponses appartiennent à la série 200, cette ligne est absente.
Keep-Alive requests
Le nombre de connexions promues à l'état de connexions persistantes.
Total body sent
Si le test a été configuré dans ce sens, il s'agit du nombre total d'octets envoyés au cours du test. Ce champ est omis si le test ne prévoyait pas d'envoi de corps.
Total transferred
Le nombre total d'octets reçus du serveur. Ce nombre correspond à peu près au nombre d'octets envoyés sur la ligne.
HTML transferred
Le nombre total d'octets utiles (contenus) reçus du serveur. Ce nombre n'inclut pas les octets correspondant aux en-têtes HTTP.
Requests per second
Il s'agit du nombre de requêtes par seconde. Il correspond au nombre de requêtes divisé par la durée totale du traitement.
Time per request
La durée moyenne du traitement d'une requête. La première valeur est calculée selon la formule concurrency * timetaken * 1000 / done, alors que la seconde valeur est calculée selon la formule timetaken * 1000 / done.
Transfer rate
Le taux de transfert calculé selon la formule totalread / 1024 / timetaken.

Bogues

De nombreux tampons de taille fixe sont déclarés statiquement. Combiné avec l'interprétation poussive des arguments de la ligne de commande, les en-têtes de réponse du serveur et autres entrées externes, ceci peut vous affecter.

HTTP/1.x n'est pas complètement implémenté ; seules certaines formes de réponses 'attendues' sont acceptées. L'utilisation relativement intense de strstr(3) provoque un affichage en tête de profil, ce qui peut faire croire à un problème de performances ; en d'autres termes, vous mesurez les performances de ab plutôt que celles du serveur.


apachectl - L'interface de contrôle du serveur HTTP Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

apachectl - L'interface de contrôle du serveur HTTP Apache

apachectl est un frontal pour le serveur HTTP Apache. Il a été conçu pour aider l'administrateur à contrôler le fonctionnement du démon Apache httpd.

Le script apachectl possède deux modes de fonctionnement. Il peut fonctionner en tant que simple frontal de la commande httpd et ne fait alors que définir toute variable d'environnement nécessaire, puis invoque httpd en lui passant tout argument de ligne de commande souhaité. Il peut aussi fonctionner en tant que script d'initialisation SysV n'acceptant qu'un seul argument tel que start, restart et stop, et traduisant ce dernier en signaux appropriés pour le démon httpd.

Si votre installation d'Apache utilise des chemins non standards, vous devrez éditer le script apachectl afin de définir les chemins appropriés pour le binaire httpd. Vous pouvez aussi spécifier tout argument de ligne de commande de httpd nécessaire. Voir les commentaires dans le script pour plus de détails.

Le script apachectl renvoie une valeur égale à 0 en cas de succès, et une valeur supérieure à 0 en cas de problème. Voir les commentaires dans le script pour plus de détails.

Voir aussi

  • Démarrer Apache
  • Arrêter Apache
  • Fichiers de configuration
  • Documentation spécifique aux plates-formes
  • httpd

Résumé

En mode frontal (pass-through), apachectl peut spécifier tous les arguments qu'accepte le binaire httpd.

apachectl [ argument-httpd ]

En mode script d'initialisation SysV, apachectl n'accepte qu'un seul des arguments définis ci-dessous.

apachectl commande

Options

Seules les options du style initialisation SysV sont décrites ici. Les autres arguments sont décrits dans la page de manuel de httpd.

start
Démarre le démon Apache httpd. Renvoie une erreur s'il est déjà en cours d'exécution. Équivalent à apachectl -k start.
stop
Arrête le démon Apache httpd. Équivalent à apachectl -k stop.
restart
Redémarre le démon Apache httpd. Si le démon n'est pas en cours d'exécution, il est démarré. Cette option vérifie automatiquement les fichiers de configuration (de la même manière que l'option configtest ) avant de lancer le redémarrage, afin d'être sûr que le fonctionnement du démon ne sera pas compromis. Equivalent à apachectl -k restart.
fullstatus
Affiche le rapport d'état complet du module mod_status. Pour que ceci fonctionne, mod_status doit être activé dans votre serveur et vous devez disposer d'un navigateur en mode texte tel que lynx sur votre système. L'URL utilisée pour accéder au rapport d'état peut être modifiée en définissant la variable STATUSURL dans le script.
status
Affiche un rapport d'état succinct. Similaire à l'option fullstatus, excepté que la liste des requêtes en cours de traitement est omise.
graceful
Redémarre le démon Apache httpd en douceur. Si le démon n'est pas en cours d'exécution, il est démarré. À la différence d'un redémarrage normal, les connexions en cours ne sont pas fermées. Comme effet de bord, les anciens fichiers journaux ne seront pas fermés immédiatement. Cela signifie que si l'on utilise un script de rotation des journaux, un délai suffisant sera nécessaire afin d'être sûr que les fichiers journaux seront bien fermés avant leur traitement par le script de rotation. Cette option vérifie automatiquement les fichiers de configuration (de la même manière que l'option configtest ) avant de lancer le redémarrage, afin d'être sûr que le fonctionnement du démon ne sera pas compromis. Équivalent à apachectl -k graceful.
graceful-stop
Arrête le démon Apache httpd en douceur. À la différence d'un arrêt normal, les connexions en cours ne sont pas fermées. Comme effet de bord, les anciens fichiers journaux ne seront pas fermés immédiatement. Équivalent à apachectl -k graceful-stop.
configtest
Effectue une vérification de la syntaxe du fichier de configuration. Avec cette option, le script parcourt le fichier de configuration et renvoie soit Syntax Ok, soit des informations détaillées à propos des éventuelles erreurs de syntaxe. Equivalent à apachectl -t.

Les options suivantes étaient disponibles dans les anciennes versions et ont été supprimées.

startssl
Pour démarrer httpd avec le support SSL, vous devez éditer votre fichier de configuration et y inclure les directives appropriées, puis utiliser la commande de démarrage normale apachectl start.


apxs - Utilitaire pour les extensions d'Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

apxs - Utilitaire pour les extensions d'Apache

apxs est un utilitaire permettant de compiler et d'installer des modules en tant qu'extensions du serveur HTTP Apache. A cet effet, un objet dynamique partagé (DSO) est compilé à partir d'un ou plusieurs fichiers sources ou objets et peut être chargé pendant l'exécution du serveur Apache via la directive LoadModule du module mod_so.

Pour pouvoir utiliser ce mécanisme d'extensions, votre plate-forme doit supporter la fonctionnalité DSO, et votre binaire httpd Apache doit être compilé avec le module mod_so. Si ce n'est pas le cas, l'utilitaire apxs vous le signalera. Vous pouvez aussi vérifier vous-même ces prérequis en exécutant manuellement la commande :

$ httpd -l

Le module mod_so doit faire partie de la liste des modules affichée. Si ces prérequis sont présents, vous pouvez facilement étendre les fonctionnalités de votre serveur Apache en installant vos propres modules à l'aide de l'utilitaire apxs, via le mécanisme DSO :

$ apxs -i -a -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/chemin/vers/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
cp mod_foo.so /chemin/vers/apache/modules/mod_foo.so
chmod 755 /chemin/vers/apache/modules/mod_foo.so
[activation du module `foo' dans /chemin/vers/apache/etc/httpd.conf]
$ apachectl restart
/chemin/vers/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/chemin/vers/apache/sbin/apachectl restart: httpd started
$ _

Les arguments fichiers peuvent correspondre à un fichier source C (.c), un fichier objet (.o) ou même une archive de bibliothèques (.a). L'utilitaire apxs reconnaît automatiquement ces extensions et utilise automatiquement les fichiers source C pour la compilation, et les fichiers objets et archives pour l'édition de liens. Cependant, si vous utilisez des fichiers objets précompilés, assurez-vous que leur code soit indépendant de la position (PIC), afin de pouvoir les utiliser avec un objet partagé chargé dynamiquement. Avec GCC, par exemple, il vous suffit de toujours utiliser l'option de compilation -fpic. Pour les autres compilateurs C, consultez leur page de manuel, ou vérifiez les drapeaux qu'apxs utilise pour compiler les fichiers objets.

Pour plus de détails à propos du support DSO dans Apache, lire la documentation du module mod_so, ou même, consultez le fichier source src/modules/standard/mod_so.c.

Voir aussi

  • apachectl
  • httpd

Syntaxe

apxs -g [ -S nom=valeur ] -n nom-module

apxs -q [ -v ] [ -S nom=valeur ] requête ...

apxs -c
    [ -S nom=valeur ]
    [ -o fichier-dso ]
    [ -I répertoire-inc ]
    [ -D nom=valeur ]
    [ -L répertoire-lib ]
    [ -l nom-bibliothèque ]
    [ -Wc,options-compilation ]
    [ -Wl,options-edition-liens ]
    fichiers ...

apxs -i
    [ -S nom=valeur ]
    [ -n nom-module ]
    [ -a ]
    [ -A ]
    fichier-dso ...

apxs -e
    [ -S nom=valeur ]
    [ -n nom-module ]
    [ -a ]
    [ -A ]
    fichier-dso ...

Options

Options courantes

-n nom-module
Définit explicitement le nom du module pour les options -i (install) et -g (génération de modèles). Utilisez cette option pour spécifier de manière explicite le nom du module. Pour l'option -g, cette option est nécessaire ; pour l'option -i, l'utilitaire apxs tente de déterminer le nom du module à partir des sources, ou (à défaut) en le déduisant du nom de fichier.

Options de requête

-q
Effectue une requête à propos des variables et de l'environnement utilisés pour compiler httpd. Lorsqu'elle est invoquée sans paramètre requête, cette option affiche toutes les variables connues, ainsi que leurs valeurs. Le paramètre optionnel -v formate la liste affichée.

Utilisez cette option pour déterminer manuellement les options utilisées pour compiler le binaire httpd qui chargera votre module. Ajoutez par exemple

INC=-I`apxs -q INCLUDEDIR`

dans vos propres Makefiles si vous devez accéder manuellement aux fichiers d'en-têtes C d'Apache.

Options de configuration

-S nom=valeur
Cette option permet de modifier la configuration d'apxs décrite ci-dessus.

Option de génération des modèles

-g
Cette option permet de générer un sous-répertoire nom (voir option -n) contenant deux fichiers : le premier fichier est un exemple de fichier source de module nommé mod_nom.c que l'on peut utiliser comme modèle pour créer ses propres modules, ou comme point de départ pour se familiariser avec le mécanisme apxs ; le second fichier est le Makefile correspondant facilitant la compilation et l'installation de ce module.

Options de compilation DSO

-c
Cette option indique une opération de compilation. Tout d'abord, les fichiers sources (.c) spécifiés par fichiers sont compilés en fichiers objets correspondants (.o), puis un objet dynamiquement partagé fichier-dso est compilé via une édition de liens de ces fichiers objets avec les autres fichiers objets (.o and .a) spécifiés par fichiers. Si l'option -o n'est pas spécifiée, le nom du fichier résultant est déduit du premier nom de fichier spécifié par fichiers, et ainsi prend en général pour valeur par défaut mod_nom.so.
-o fichier-dso
Spécifie de manière explicite le nom de fichier de l'objet partagé dynamiquement créé. Sans cette option, et si le nom ne peut pas être déduit de la liste fichiers, c'est le nom par défaut mod_unknown.so qui sera utilisé.
-D nom=valeur
Cette option est transmise directement à la commande de compilation. Vous pouvez l'utiliser pour ajouter vos propres définitions au processus de compilation.
-I répertoire-inc
Cette option est transmise directement à la commande de compilation. Vous pouvez l'utiliser pour ajouter vos propres chemins de recherche des répertoires include au processus de compilation.
-L répertoire-lib
Cette option est transmise directement à la commande d'édition de liens. Vous pouvez l'utiliser pour ajouter vos propres chemins de recherche des répertoires de bibliothèques au processus de compilation.
-l nom-bibliothèque
Cette option est transmise directement à la commande d'édition de liens. Vous pouvez l'utiliser pour ajouter vos propres bibliothèques à rechercher au processus de compilation.
-Wc,options-compilation
Cette option transmet les options-compilation en tant qu'options supplémentaires à la commande libtool --mode=compile. Vous pouvez l'utiliser pour ajouter des options locales spécifiques au compilateur.
-Wl,options-edition-liens
Cette option transmet les options-edition-liens en tant qu'options supplémentaires à la commande libtool --mode=link. Vous pouvez l'utiliser pour ajouter des options locales spécifiques à l'éditeur de liens.
-p
Avec cette option, apxs effectue l'édition de liens avec les bibliothèques apr/apr-util. Elle permet de compiler les programmes helper qui utilisent les bibliothèques apr/apr-util.

Options d'installation et de configuration DSO

-i
Cette option indique une opération d'installation et installe un ou plusieurs objets dynamiquement partagés dans le répertoire modules du serveur.
-a
Cette option active le module en ajoutant automatiquement une directive LoadModule correspondante au fichier de configuration d'Apache httpd.conf, ou en l'activant s'il existe déjà.
-A
Identique à l'option -a, à la différence que la directive LoadModule créée est préfixée par un caractère dièse (#) ; le module est ainsi préparé pour une activation ultérieure, mais est désactivé dans un premier temps.
-e
Cette option indique une opération d'édition de liens et peut être utilisée avec les options -a et -A de la même manière qu'au cours de l'opération d'installation pour éditer le fichier de configuration d'Apache httpd.conf, sans toutefois installer le module.

Exemples

Supposons que vous disposiez d'un module Apache nommé mod_foo.c et destiné à étendre les fonctionnalités du serveur. Pour ce faire, vous devez tout d'abord compiler le fichier source C en un objet partagé pouvant être chargé dans le serveur Apache à l'exécution, via la commande suivante :

$ apxs -c mod_foo.c
/chemin/vers/libtool --mode=compile gcc ... -c mod_foo.c
/chemin/vers/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
$ _

Vous devez ensuite vérifier la configuration d'Apache en vous assurant qu'une directive LoadModule est bien présente pour charger cet objet partagé. Pour simplifier cette étape, apxs propose une méthode automatique d'installation de l'objet partagé dans son répertoire "modules", et de mise à jour du fichier httpd.conf en conséquence. Pour bénéficier de cette automatisation, utilisez la commande suivante :

$ apxs -i -a mod_foo.la
/chemin/vers/instdso.sh mod_foo.la /chemin/vers/apache/modules
/chemin/vers/libtool --mode=install cp mod_foo.la /chemin/vers/apache/modules ... chmod 755 /chemin/vers/apache/modules/mod_foo.so
[activation du module `foo' dans /chemin/vers/apache/conf/httpd.conf]
$ _

Une ligne contenant

LoadModule foo_module modules/mod_foo.so

est alors ajoutée au fichier de configuration si ce n'est pas déjà fait. Si vous voulez que le module soit désactivé par défaut, utilisez l'option -A comme suit :

$ apxs -i -A mod_foo.c

Pour un test rapide du mécanisme apxs, vous pouvez créer un exemple de modèle de module Apache, ainsi que le Makefile correspondant via :

$ apxs -g -n foo
Creating [DIR] foo
Creating [FILE] foo/Makefile
Creating [FILE] foo/modules.mk
Creating [FILE] foo/mod_foo.c
Creating [FILE] foo/.deps
$ _

Vous pouvez ensuite compiler immédiatement ce module exemple en objet partagé et le charger dans le serveur Apache :

$ cd foo
$ make all reload
apxs -c mod_foo.c
/chemin/vers/libtool --mode=compile gcc ... -c mod_foo.c
/chemin/vers/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
apxs -i -a -n "foo" mod_foo.la
/chemin/vers/instdso.sh mod_foo.la /chemin/vers/apache/modules
/chemin/vers/libtool --mode=install cp mod_foo.la /chemin/vers/apache/modules ... chmod 755 /chemin/vers/apache/modules/mod_foo.so
[activation du module `foo' dans /chemin/vers/apache/conf/httpd.conf]
apachectl restart
/chemin/vers/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/chemin/vers/apache/sbin/apachectl restart: httpd started
$ _


configure - Configure l'arborescence des sources - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

configure - Configure l'arborescence des sources

Le script configure permet de configurer l'arborescence des sources afin de compiler et installer le serveur HTTP Apache sur votre plate-forme spécifique. De nombreuses options vous permettent de compiler un serveur correspondant à vos propres besoins.

Ce script, situé dans le répertoire racine de la distribution des sources, ne concerne que la compilation sur les systèmes Unix et apparentés. Pour les autres plates-formes, voir la documentation spécifique de ces dernières.

Voir aussi

  • Compilation et installation

Résumé

Vous devez appeler le script configure depuis le répertoire racine de la distribution.

./configure [OPTION]... [VARIABLE=VALEUR]...

Pour définir des variables d'environnement (par exemple CC,CFLAGS, etc...), utilisez la clause VARIABLE=VALEUR. Voir ci-dessous pour la description de quelques variables usuelles.

Options

  • Options de Configuration
  • Répertoires d'installation
  • Types de Systèmes
  • Fonctionnalités optionnelles
  • Options pour les programmes support

Options de Configuration

Les options suivantes affectent le comportement du script configure.

-C
--config-cache
C'est un alias pour --cache-file=config.cache
--cache-file=FICHIER
Les résultats des tests seront mis en cache dans le fichier FICHIER. Cette option est désactivée par défaut.
-h
--help [short|recursive]
Affichage de l'aide et sortie du script. Avec l'argument short, seules les options spécifiques à ce paquet seront affichées. L'argument recursive permet d'afficher l'aide de tous les paquets inclus.
-n
--no-create
Le script configure s'exécute normalement, mais ne crée pas les fichiers résultants. Ceci permet de vérifier les résultats des tests avant de générer les fichiers makefile pour la compilation.
-q
--quiet
Les messages checking ... ne sont pas affichés au cours du processus de configuration.
--srcdir=DIR
Définit le répertoire DIR comme répertoire des fichiers sources. Par défaut, c'est le répertoire où se situe le script configure, ou le répertoire parent.
--silent
Identique à --quiet
-V
--version
Affichage des informations de copyright et sortie du script.

Répertoires d'installation

Ces options permettent de spécifier le répertoire d'installation. L'arborescence de l'installation dépend de l'organisation (layout) sélectionnée.

--prefix=PREFIX
Installe les fichiers indépendants de l'architecture dans PREFIX. Par défaut, le répertoire d'installation est /usr/local/apache2.
--exec-prefix=EPREFIX
Installe les fichiers dépendants de l'architecture dans EPREFIX. La valeur par défaut de cette option correspond à la valeur de la variable PREFIX.

Par défaut, make install va installer tous les fichiers dans /usr/local/apache2/bin, /usr/local/apache2/lib, etc... Vous pouvez cependant spécifier un préfixe d'installation autre que /usr/local/apache2 en utilisant l'option --prefix (par exemple --prefix=$HOME).

Spécifier une organisation (layout) des répertoires

--enable-layout=LAYOUT
Configure le code source et les scripts de compilation de façon à ce que l'arborescence d'installation adopte l'organisation LAYOUT. Ceci vous permet de spécifier des chemins séparés pour chaque type de fichier de l'installation du serveur HTTP Apache. Le fichier config.layout contient de nombreux exemples de configurations, et vous pouvez créer vos propres configurations personnalisées en vous basant sur ces exemples. Les différentes organisations contenues dans ce fichier sont enregistrées sous forme de sections <Layout FOO>...</Layout> et référencées dans ce cas par le nom FOO. L'organisation par défaut est Apache.

Configuration avancée des répertoires d'installation

Pour une définition plus précise des répertoires d'installation, utilisez les options ci-dessous. Notez que les répertoires par défaut sont définis par autoconf, et que leurs valeurs sont écrasées par les valeurs correspondantes définies lors du choix de l'organisation des répertoires (layout).

--bindir=DIR
Installe les exécutables utilisateur dans DIR. Les exécutables utilisateur sont des programmes support comme htpasswd, dbmmanage, etc..., et destinés aux administrateurs du site. Par défaut, DIR est défini à EPREFIX/bin.
--datadir=DIR
Installe les données non modifiables indépendantes de l'architecture dans DIR. Par défaut, datadir est défini à PREFIX/share. Cette option est fournie par autoconf et actuellement inutilisée.
--includedir=DIR
Installe les fichiers d'en-têtes C dans DIR. Par défaut, includedir est défini à EPREFIX/include.
--infodir=DIR
Installe la documentation info dans DIR. Par défaut, infodir est défini à PREFIX/info. Cette option est actuellement inutilisée.
--libdir=DIR
Installe les fichiers objet des bibliothèques dans DIR. Par défaut, libdir est défini à EPREFIX/lib.
--libexecdir=DIR
Installe les exécutables du programme (autrement dit les modules partagés) dans DIR. Par défaut, libexecdir est défini à EPREFIX/modules.
--localstatedir=DIR
Installe les données temporaires modifiables spécifiques à la machine dans DIR. Par défaut, localstatedir est défini à PREFIX/var. Cette option est fournie par autoconf et est actuellement inutilisée.
--mandir=DIR
Installe les pages de manuel dans DIR. Par défaut, mandir est défini à EPREFIX/man.
--oldincludedir=DIR
Installe les fichiers d'en-têtes C pour les programmes autres que gcc dans DIR. Par défaut, oldincludedir est défini à /usr/include. Cette option est fournie par autoconf et est actuellement inutilisée.
--sbindir=DIR
Installe les exécutables de l'administrateur système dans DIR. Ce sont les programmes du serveur comme httpd, apachectl, suexec, etc..., qui sont nécessaires à l'exécution du serveur HTTP Apache. Par défaut, sbindir est défini à EPREFIX/sbin.
--sharedstatedir=DIR
Installe les données modifiables indépendantes de l'architecture dans DIR. Par défaut, sharedstatedir est défini à PREFIX/com. Cette option est fournie par autoconf et est actuellement inutilisée.
--sysconfdir=DIR
Installe les données non modifiables spécifiques à la machine comme les fichiers de configuration du serveur httpd.conf, mime.types, etc... dans DIR. Par défaut, sysconfdir est défini à PREFIX/conf.

Types de systèmes

Ces options sont utilisées pour la cross-compilation du serveur HTTP Apache afin de pouvoir l'utiliser sur un autre système. Dans le cas général où la compilation et l'exécution du serveur ont lieu sur le même système, ces options ne sont pas utilisées.

--build=BUILD
Définit le type du système sur lequel les outils sont compilés. Par défaut, il s'agit de la chaîne renvoyée par le script config.guess.
--host=HOST
Définit le type du système sur lequel le serveur s'exécutera. Par défaut, HOST est identique à BUILD.
--target=TARGET
Configure pour construire des compilateurs pour le type de système TARGET. Par défaut, TARGET est identique à HOST. Cette option est fournie par autoconf et n'est pas requise par le serveur HTTP Apache.

Fonctionnalités optionnelles

Ces options vous permettent de configurer avec précision les fonctionnalités de votre futur serveur HTTP.

Syntaxe générale

D'une manière générale, vous pouvez utiliser la syntaxe suivante pour activer ou désactiver une fonctionnalité :

--disable-FONCTIONNALITE
Désactive la fonctionnalité FONCTIONNALITE. Identique à --enable-FONCTIONNALITE=no.
--enable-FONCTIONNALITE[=ARG]
Active la fonctionnalité FONCTIONNALITE. La valeur par défaut de ARG est yes.
--enable-MODULE=shared
Le module spécifié sera compilé en tant que module DSO. Par défaut, les modules activés sont liés dynamiquement.
--enable-MODULE=static
Le module correspondant sera lié statiquement.

Note

Si vous spécifiez --enable-foo, et si foo n'existe pas, configure ne le signalera pas ; vous devez donc prendre soin de taper les options correctement.

Choix des modules à compiler

La plupart des modules sont compilés par défaut et ils doivent être désactivés de manière explicite ou via le mots-clé few (voir ci-dessous --enable-modules, --enable-mods-shared et --enable-mods-static pour une explication plus détaillée), ou --enable-modules=none pour les désactiver tous.

Par défaut, les autres modules ne sont pas compilés et doivent être activés explicitement, ou en utilisant les mots-clés all ou reallyall pour être disponibles.

Pour déterminer quels modules sont compilés par défaut, exécutez la commande ./configure -h ou ./configure --help, et consultez les Optional Features. Par exemple, supposons que vous soyez intéressé par les modules mod_example1 et mod_example2, et que vous voyiez ceci :

Optional Features:
  ...
  --disable-example1     example module 1
  --enable-example2      example module 2
  ...

Le module mod_example1 est ici activé par défaut, et vous devez spécifier --disable-example1 si vous ne voulez pas le compiler. Par contre, le module mod_example2 est désactivé par défaut, et vous devez spécifier --enable-example2 si vous voulez le compiler.

Modules Multi-Processus

Les Modules Multi-Processus, ou MPMs, constituent le coeur du serveur. Un seul MPM doit être actif pour que le serveur puisse fonctionner. Vous trouverez la liste des MPMs disponibles à module index page.

Les MPMs peuvent être compilés en tant que modules DSO pour un chargement dynamique, ou liés statiquement avec le serveur, et sont activés via les options suivantes :

--with-mpm=MPM

Sélectionne le MPM par défaut pour votre serveur. Si les MPMs sont compilés en tant que modules DSO (voir --enable-mpms-shared), cette option spécifie le MPM qui sera chargé par défaut selon le fichier de configuration. Dans le cas contraire, cette option spécifie le seul MPM disponible qui sera lié statiquement avec le serveur.

Si cette option est omise, c'est le MPM par défaut pour votre système d'exploitation qui sera utilisé.

--enable-mpms-shared=Liste de MPM

Définit une liste de MPMs à compiler en tant que modules dynamiquement partagés (DSO). Un de ces modules doit être chargé dynamiquement via la directive LoadModule.

Liste de MPM est une liste, entourée d'apostrophes, de noms de MPM séparés par des espaces. Par exemple :

--enable-mpms-shared='prefork worker'

Vous pouvez aussi utiliser le mot-clé all, ce qui aura pour effet de spécifier tous les MPMs qui supportent le chargement dynamique sur la plate-forme considérée, et de les compiler en tant que modules DSO. Par exemple :

--enable-mpms-shared=all

Modules tiers

Pour ajouter des modules tiers, utilisez les options suivantes :

--with-module=type-module:fichier-module[, type-module:fichier-module]

Ajoute un ou plusieurs modules tiers à la liste des modules liés statiquement. Le fichier source du module fichier-module sera recherché dans le sous-répertoire type-module de l'arborescence des sources de votre serveur HTTP Apache. S'il ne l'y trouve pas, configure considèrera fichier-module comme un chemin de fichier absolu et essaiera de copier le fichier source dans le sous-répertoire type-module. Si ce sous-répertoire n'existe pas, il sera créé et un fichier Makefile.in standard y sera enregistré.

Cette option est conçue pour ajouter de petits modules externes ne comportant qu'un seul fichier source. Pour des modules plus complexes, vous devrez lire la documentation du fournisseur du module.

Note

Si vous voulez compiler un module DSO (lié de manière dynamique au lieu de statique), utilisez le programme apxs.

Options cumulatives et autres options

--enable-maintainer-mode
Active les avertissements de débogage et de compilation et charge tous les modules compilés.
--enable-mods-shared=LISTE-MODULES

Définit une liste de modules à activer et à compiler en tant que modules dynamiques partagés. Cela signifie que ces modules doivent être chargés dynamiquement en utilisant la directive LoadModule.

LISTE-MODULES est une liste, entourée d'apostrophes, de noms de modules séparés par des espaces. Les noms des modules sont spécifiés sans le préfixe mod_. Par exemple :

--enable-mods-shared='headers rewrite dav'

Vous pouvez aussi utiliser les mots-clés reallyall, all, most et few. Par exemple,

--enable-mods-shared=most

va compiler la plupart des modules en tant que modules DSO,

--enable-mods-shared=few

ne compilera qu'un jeu de modules de base.

Le jeu par défaut correspond au mot-clé most.

Les directives LoadModule correspondant aux différents modules choisis sont automatiquement générées dans le fichier de configuration principal. Par défaut, toutes ces directives sont mises en commentaire, sauf pour les modules requis ou ceux explicitement sélectionnés par un argument --enable-nom-module du script configure. Vous pouvez modifier le jeu de modules chargé en activant ou désactivant les directives LoadModule dans le fichier httpd.conf. En outre, les directives LoadModule peuvent être activées pour tous les modules compilés via l'option --enable-load-all-modules du script configure.

--enable-mods-static=MODULE-LIST
Cette option produit le même effet que l'option --enable-mods-shared, à l'exception que les modules seront liés statiquement. Cela signifie que les modules spécifiés seront toujours disponibles au cours du fonctionnement de httpd. Ils n'ont pas besoin d'être chargés via la directive LoadModule.
--enable-modules=MODULE-LIST
Cette option se comporte comme --enable-mods-shared, et va aussi lier les modules concernés dynamiquement. Le mot-clé spécial none désactive la compilation de tous les modules.
--enable-v4-mapped
Permet aux sockets IPv6 de traiter les connexions IPv4.
--with-port=PORT
Permet de définir le port que le programme httpd va écouter. Ce numéro de port est utilisé lors de la génération du fichier de configuration httpd.conf. Sa valeur par défaut est 80.
--with-program-name
Permet de définir un nom d'exécutable alternatif. Le nom par défaut est httpd.

Paquets optionnels

Ces options permettent de définir des paquets optionnels.

Syntaxe générale

D'une manière générale, vous pouvez utiliser la syntaxe suivante pour définir un paquet optionnel :

--with-PAQUET[=ARG]
Utilise le paquet PAQUET. La valeur par défaut de ARG est yes.
--without-PAQUET
N'utilise pas le paquet PAQUET. Cette option est identique à --with-PAQUET=no. Elle est fournie par autoconf mais n'est pas très utile pour le serveur HTTP Apache.

Paquets spécifiques

--with-apr=REP|FICHIER
La Bibliothèque pour la portabilité d'Apache ou Apache Portable Runtime (APR) fait partie de la distribution des sources de httpd et est compilée automatiquement avec le serveur HTTP. Si vous voulez utiliser une APR déjà installée à la place, vous devez indiquer à configure le chemin du script apr-config. Vous pouvez spécifier le chemin absolu et le nom ou le répertoire d'installation de l'APR. apr-config doit se trouver dans ce répertoire ou dans le sous-repertoire bin.
--with-apr-util=REP|FICHIER
Les utilitaires pour la Bibliothèque pour la portabilité d'Apache ou Apache Portable Runtime Utilities (APU) font partie de la distribution des sources de httpd et sont compilés automatiquement avec le serveur HTTP. Si vous voulez utiliser des APU déjà installés à la place, vous devez indiquer à configure le chemin du script apu-config. Vous pouvez spécifier le chemin absolu et le nom ou le répertoire d'installation des APU. apu-config doit se trouver dans ce répertoire ou dans le sous-repertoire bin.
--with-ssl=REP
Si mod_ssl a été activé, configure recherche une installation d'OpenSSL. Vous pouvez définir le répertoire de la boîte à outils SSL/TLS à la place.
--with-z=REP
configure recherche automatiquement une bibliothèque zlib installée si la configuration de vos sources en nécessite une (par exemple lorsque mod_deflate est activé). Vous pouvez définir le répertoire de la bibliothèque de compression à la place.

De nombreuses fonctionnalités du serveur HTTP Apache, y compris les directives RewriteMap DBM de mod_rewrite et mod_authn_dbm utilisent une base de données simple de la forme clé/valeur pour une recherche rapide d'informations. SDBM, inclus dans les APU, est donc toujours disponible. Si vous souhaitez utiliser d'autres types de bases de données, utilisez les options suivantes afin de les activer :

--with-gdbm[=chemin]
Si aucun chemin n'est spécifié, configure va rechercher les fichiers d'en-têtes et les bibliothèques d'une installation DBM GNU dans les chemins standards. Avec un chemin explicite, configure recherchera les fichiers concernés dans chemin/lib et chemin/include. En fait, chemin permet de spécifier plusieurs chemins d'en-têtes et bibliothèques spécifiques en les séparant par des caractères ':'.
--with-ndbm[=chemin]
Identique à --with-gdbm, mais recherche une installation de New DBM.
--with-berkeley-db[=chemin]
Identique à --with-gdbm, mais recherche une installation de Berkeley DB.

Note

Les options DBM sont fournies par les APU et passées en paramètres à son script de configuration. Elles sont inutiles lorsqu'on utilise des APU déjà installés définis par --with-apr-util.

Vous pouvez utiliser plusieurs implémentations DBM avec votre serveur HTTP. Le type DBM approprié sera choisi au cours de la configuration de l'exécution à chaque démarrage.

Options pour les programmes de support

--enable-static-support
Permet de compiler une version des binaires de support liés statiquement. En d'autres termes, la compilation produira un exécutable indépendant comportant toutes les bibliothèques nécessaires. Sans cette option, les binaires de supports sont liés dynamiquement.
--enable-suexec
Utilisez cette option pour activer la programme suexec, qui vous permet de définir un uid et un gid pour les processus lancés. N'utilisez cette option que si vous maîtrisez toutes les implications en matière de sécurité de l'exécution d'un binaire suid sur votre serveur. D'autres options permettent de configurer suexec comme décrit ci-dessous.

Il est possible de lier statiquement le binaire d'un programme support particulier en utilisant les options suivantes :

--enable-static-ab
Compile une version liée statiquement du programme ab.
--enable-static-checkgid
>Compile une version liée statiquement du programme checkgid.
--enable-static-htdbm
Compile une version liée statiquement du programme htdbm.
--enable-static-htdigest
Compile une version liée statiquement du programme htdigest.
--enable-static-htpasswd
Compile une version liée statiquement du programme htpasswd.
--enable-static-logresolve
Compile une version liée statiquement du programme logresolve.
--enable-static-rotatelogs
Compile une version liée statiquement du programme rotatelogs.

Options de configuration de suexec

Les options suivantes permettent de définir avec précision le comportement du programme suexec. Voir Configurer et installer suEXEC pour plus de détails.

--with-suexec-bin
Définit le chemin du binaire suexec. La valeur par défaut est --sbindir (voir Définition précise des répertoires d'installation).
--with-suexec-caller
Définit l'utilisateur qui a l'autorisation d'appeler suexec. Il est en général souhaitable que ce soit le même que celui sous lequel httpd s'exécute.
--with-suexec-docroot
Définit l'arborescence des répertoires dans laquelle le lancement des exécutables via suexec est autorisé. La valeur par défaut est --datadir/htdocs.
--with-suexec-gidmin
Définit la valeur de GID la plus basse autorisée comme valeur cible pour suexec. La valeur par défaut est 100.
--with-suexec-logfile
Définit le nom du fichier journal de suexec. La valeur par défaut est --logfiledir/suexec_log.
--with-suexec-safepath
Définit la valeur de la variable d'environnement PATH pour les processus lancés par suexec. La valeur par défaut est /usr/local/bin:/usr/bin:/bin.
--with-suexec-userdir
Définit le sous-répertoire du répertoire utilisateur qui contient tous les exécutables pouvant être lancés par suexec. Cette option est nécessaire si vous souhaitez utiliser suexec avec des répertoires utilisateurs (définis via mod_userdir). La valeur par défaut est public_html.
--with-suexec-uidmin
Définit la valeur d'UID la plus basse autorisée comme valeur cible pour suexec. La valeur par défaut est 100.
--with-suexec-umask
Définit le masque de permissions umask pour les processus lancés par suexec. Il correspond par défaut au masque défini par la configuration de votre système.

Variables d'environnement

Certaines variables d'environnement permettent de modifier les choix effectués par configure, ou d'aider ce dernier à trouver les bibliothèques et programmes possédant des noms et chemins non standards.

CC
Définit la commande du compilateur C à utiliser pour la compilation.
CFLAGS
Définit les paramètres du compilateur C que vous voulez utiliser pour la compilation.
CPP
Définit la commande du préprocesseur C à utiliser.
CPPFLAGS
Définit les paramètres du préprocesseur C/C++, par exemple -Irépertoire-include, si certains de vos fichiers d'en-têtes se trouvent dans le répertoire non standard répertoire-include.
LDFLAGS
Définit les paramètres de l'éditeur de liens, par exemple -Lrépertoire-lib, si certaines de vos bibliothèques se trouvent dans le répertoire non standard répertoire-lib.


dbmmanage - Gestion des fichiers d'authentification des utilisateurs au format DBM - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

dbmmanage - Gestion des fichiers d'authentification des utilisateurs au format DBM

dbmmanage permet de créer et de maintenir les fichiers au format DBM où sont stockés les noms d'utilisateurs et mots de passe à des fins d'authentification de base des utilisateurs HTTP via le module mod_authn_dbm. Il est possible de restreindre l'accès aux ressources disponibles sur le serveur HTTP Apache aux seuls utilisateurs spécifiés dans les fichiers créés par dbmmanage. Ce programme ne peut être utilisé qu'avec des fichiers d'utilisateurs au format DBM. Pour l'utilisation de fichiers textes, voir le programme htpasswd.

Le programme htdbm est aussi un utilitaire permettant de maintenir une base de données de mots de passe DBM.

Cette page de manuel ne décrit que les arguments de la ligne de commande. Pour plus de détails à propos des directives nécessaires pour configurer l'authentification des utilisateurs dans httpd, voir le manuel httpd qui est fourni avec la distribution d'Apache, ou peut être consulté à http://httpd.apache.org/.

Voir aussi

  • httpd
  • htdbm
  • mod_authn_dbm
  • mod_authz_dbm

Syntaxe

dbmmanage [ codage ] nom-fichier add|adduser|check|delete|update nom-utilisateur [ mot-de-passe-chiffré [ groupe[,groupe...] [ commentaire ] ] ]

dbmmanage nom-fichier view [ nom-utilisateur ]

dbmmanage nom-fichierimport

Options

nom-fichier
Le nom du fichier au format DBM, en général sans l'extension .db, .pag, ou .dir.
nom-utilisateur
L'utilisateur concerné par l'opération effectuée. Le nom-utilisateur ne doit pas contenir de caractère :.
mot-de-passe-chiffré
C'est le mot de passe sous sa forme chiffrée à utiliser avec les commandes update et add. Vous pouvez utiliser un tiret (-) si vous voulez que le mot de passe vous soit demandé, mais remplissez les champs par la suite. En outre, avec la commande update, un point (.) permet de conserver le mot de passe original.
groupe
Un groupe dont l'utilisateur est membre. Un nom de groupe ne doit pas contenir de caractère (:). Vous pouvez utiliser un tiret (-) si vous ne voulez pas associer l'utilisateur à un groupe, mais remplissez le champ commentaire. En outre, avec la commande update, un point (.) permet de conserver le groupe original.
commentaire
C'est l'endroit où vous pouvez enregistrer diverses informations à propos de l'utilisateur telles que son nom réel, sont e-mail, etc... Le serveur ignore ce champ.

Codages

-d
chiffrement crypt (chiffrement par défaut sauf sous Win32, Netware)
-m
chiffrement MD5 (chiffrement par défaut sous Win32, Netware)
-s
chiffrement SHA1
-p
en clair (déconseillé)

Commandes

add
Ajoute une entrée pour nom-utilisateur à nom-fichier en utilisant le mot de passe chiffré mot-de-passe-chiffré.

dbmmanage passwords.dat add rbowen foKntnEF3KSXA

adduser
Demande un mot de passe puis ajoute une entrée pour nom-utilisateur à nom-fichier.

dbmmanage passwords.dat adduser krietz

check
Demande un mot de passe puis vérifie si nom-utilisateur est présent dans nom-fichier et si son mot de passe correspond au mot de passe fourni.

dbmmanage passwords.dat check rbowen

delete
Supprime l'entrée nom-utilisateur de nom-fichier.

dbmmanage passwords.dat delete rbowen

import
Lit les entrées nom-utilisateur:mot-de-passe (une par ligne) depuis STDIN, et les ajoute à nom-fichier. Les mots de passe doivent être déjà chiffrés.
update
Identique à la commande adduser, à l'exception que la présence de nom-utilisateur dans nom-fichier est vérifiée.

dbmmanage passwords.dat update rbowen

view
Affiche le contenu du fichier DBM. Si vous spécifiez un nom-utilisateur, seule l'entrée correspondante est affichée.

dbmmanage passwords.dat view

Bogues

Vous devez garder à l'esprit qu'il existe de nombreux formats de fichiers DBM différents, et que selon toute vraisemblance, des bibliothèques pour plus d'un format sont présentes sur votre système. Les trois exemples de base sont SDBM, NDBM, le projet GNU GDBM, et Berkeley DB 2. Malheureusement, toutes ces bibliothèques utilisent des formats de fichiers différents, et vous devez vous assurer que le format de fichier utilisé par nom-fichier correspond au format attendu par dbmmanage. Actuellement, dbmmanage n'a aucun moyen de savoir à quel type de fichier DBM il a à faire. S'il est utilisé avec un format inapproprié, il ne renverra rien, ou pourra créer un fichier DBM différent avec un nom différent, ou au pire, va corrompre le fichier DBM si vous avez tenté de le modifier.

dbmmanage possède une liste de préférences en matière de formats DBM, définies dans le tableau @AnyDBM::ISA au début du programme. Comme nous préférons le format de fichier Berkeley DB 2, l'ordre dans lequel dbmmanage va rechercher les bibliothèques système est Berkeley DB 2, puis NDBM, GDBM et enfin SDBM. La première bibliothèque trouvée sera celle que dbmmanage tentera d'utiliser pour toutes les opérations sur les fichiers DBM. Cette ordre est sensiblement différent de l'ordre standard de Perl @AnyDBM::ISA, et de l'ordre utilisé par l'appel dbmopen() de Perl ; si vous utilisez un autre utilitaire pour gérer vos fichiers DBM, il doit donc se conformer à l'ordre de préférence indiqué précédemment. Vous devez prêter la même attention si vous utilisez des programmes écrits dans d'autres langages, comme C, pour accéder à ces fichiers.

Vous pouvez utiliser le programme file fourni par la plupart des systèmes Unix pour déterminer le format d'un fichier DBM.


fcgistarter - Démarrer un programme FastCGI - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

fcgistarter - Démarrer un programme FastCGI

Voir aussi

  • mod_proxy_fcgi

Note

Ne fonctionne actuellement que sur les systèmes de type Unix.

Syntaxe

fcgistarter -c commande -p port [ -i interface ] -N nombre

Options

-c commande
Le programme FastCGI
-p port
Port sur lequel le programme va se mettre en écoute
-i interface
Interface sur laquelle le programme va se mettre en écoute
-N nombre
Nombre d'instances du programme


htcacheclean - Nettoyage du cache sur disque - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

htcacheclean - Nettoyage du cache sur disque

htcacheclean permet de maintenir la taille de l'espace de stockage réservé à mod_disk_cache en dessous d'une limite de taille donnée ou d'inodes utilisés. Cet utilitaire peut s'exécuter soit manuellement, soit en mode démon. Lorsqu'il fonctionne en mode démon, il se met en attente en arrière-plan et recherche à intervalles réguliers dans le répertoire du cache les contenus à supprimer. Pour arrêter proprement le démon, vous pouvez lui envoyer un signal TERM ou INT. Lorsqu'il est lancé manuellement, une recherche des contenus du cache qui peuvent être supprimés est effectuée une seule fois. Si une ou plusieurs URLs sont spécifiées, chacune d'entre elles sera supprimée du cache, si elle est présente.

Voir aussi

  • mod_disk_cache

Syntaxe

htcacheclean
    [ -D ]
    [ -v ]
    [ -t ]
    [ -r ]
    [ -n ]
    [ -Rarrondi ]
    -pchemin
    [-llimite|
    -Llimite]

htcacheclean [ -n ] [ -t ] [ -i ] [ -Pfichier-pid ] [ -Rarrondi ] -dintervalle -pchemin [-llimite| -Llimite]

htcacheclean [ -v ] [ -Rarrondi ] -pchemin [ -a ] [ -A ]

htcacheclean [ -D ] [ -v ] [ -t ] [ -Rarrondi ] -pchemin url

Options

-dintervalle
Configure en mode démon et planifie le nettoyage du cache toutes les intervalle minutes. Cette option et les options -D, -v et -r s'excluent mutuellement. Pour arrêter le démon proprement, il suffit de lui envoyer un signal SIGTERM ou SIGINT.
-D
Le programme s'exécute mais ne supprime aucun contenu ("dry run"). Cette option et l'option -d s'excluent mutuellement. Si ce mode est combiné avec la suppression des répertoires avec -t, les inodes signalés comme supprimés dans les statistiques ne peuvent pas prendre en compte les répertoires supprimés, et seront marqués en tant qu'estimation.
-v
Exécution verbeuse et affichage de statistiques. Cette option et l'option -d s'excluent mutuellement.
-r
Nettoyage en profondeur. Le serveur web Apache doit être arrêté (dans le cas contraire, il risque de rester des déchets dans le cache). Cette option implique l'option -t et s'exclue mutuellement avec l'option -d.
-n
Exécution en retrait. L'exécution du programme est ralentie en faveur des autres processus. htcacheclean s'interrompt de temps en temps de façon à ce que a) les entrées/sorties disque soient retardées et b) que le noyau puisse mettre ce temps processeur à disposition des autres processus.
-t
Supprime tous les répertoires vides. Par défaut, seuls les fichiers sont supprimés du cache ; avec certaines configurations, cependant, un grand nombre de répertoires sont créés et méritent que l'on y prête attention. Si votre configuration nécessite un grand nombre de répertoires, au point que le remplissage de la table d'inodes ou d'allocation de fichiers puisse poser problème, l'utilisation de cette option est conseillée.
-pchemin
Définit chemin comme répertoire racine du cache sur disque. Cette valeur doit correspondre à celle spécifiée par la directive CacheRoot.
-Pfichier-pid
Permet de spécifier fichier-pid comme nom du fichier dans le lequel sera enregistré l'identifiant du processus en mode démon.
-Rround
Permet de spécifier le plus petit commun multiple de la taille du cache, afin de tenir compte de la taille des blocs. Définir ce paramètre à la taille d'un bloc de la partition du cache.
-llimite
Définit limite comme la taille maximale du cache sur disque. La valeur s'exprime par défaut en octets (ou en ajoutant le suffixe B à la valeur). Ajoutez le suffixe K pour KOctets ou M pour MOctets.
-Llimite
Spécifie limite comme la limite totale en inodes du cache disque.
-i
Exécution intelligente. Le programme ne s'exécute que lorsque le cache sur disque a été modifié. Cette option ne peut s'utiliser qu'avec l'option -d.
-a
Affiche la liste des URLs actuellement stockées dans le cache. Les variantes de la même URL seront listées une seule fois par variante.
-A
Affiche la liste des URLs actuellement stockées dans le cache, ainsi que leurs attributs dans l'ordre suivant : url, header size, body size, status, entity version, date, expiry, request time, response time, body present, head request.

Suppression d'une URL particulière

Si une ou plusieurs URLs sont passées en argument à htcacheclean, chacune d'entre elles sera supprimée du cache. S'il existe plusieurs variantes de ces URLs, elles seront toutes supprimées.

Lorsqu'une URL mandatée en inverse doit être supprimée, l'URL effective est construite à partir de l'en-tête Host, du port, du chemin et de la requête. Notez que le '?' doit toujours être spécifié explicitement dans l'URL, qu'une chaîne de paramètres soit présente ou non. Par exemple, pour supprimer le chemin / du serveur localhost, l'URL devra être spécifiée comme suit : http://localhost:80/?.

Affichage des URLs présentes dans le cache

Les options -a ou -A permettent d'afficher les URLs présentes dans le cache telles qu'elles s'y trouvent, une URL par ligne. L'option -A affiche l'entrée du cache complète pour chaque URL, avec ses différents champs dans l'ordre suivant :

url
L'URL de l'entrée considérée.
header size
La taille de l'en-tête en octets.
body size
La taille du corps en octets.
status
Etat de la réponse en cache.
entity version
Le nombre de fois que cette entrée a été revalidée sans être effacée.
date
Date de la réponse.
expiry
Date d'expiration de la réponse.
request time
Date du début de la requête.
response time
Date de la fin de la requête.
body present
Ce champ contient la valeur 0 si aucun corps n'est stocké avec cette requête, 1 dans le cas contraire.
head request
Ce champ contient la valeur 1 si l'entrée comporte une requête HEAD en cache sans corps, 0 dans le cas contraire.

Valeur renvoyée

htcacheclean renvoie zéro ("true") si toutes les opérations se sont déroulées normalement, et 1 dans le cas contraire. Si une URL est spécifiée, et si cette URL était présente dans le cache et a été supprimée avec succès, htcacheclean renvoie 0, et 2 dans le cas contraire. Si une erreur est survenue au cours de la suppression de l'URL, htcacheclean renvoie 1.


htdbm - Manipuler des bases de données DBM de mots de passe - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

htdbm - Manipuler des bases de données DBM de mots de passe

htdbm permet de manipuler des fichiers au format DBM ou sont stockés des nom d'utilisateurs et mots de passe à des fins d'authentification de base des utilisateurs HTTP via le module mod_authn_dbm. Voir la documentation de dbmmanage pour plus de détails à propos de ces fichiers DBM.

Voir aussi

  • httpd
  • dbmmanage
  • mod_authn_dbm

Syntaxe

htdbm [ -TDBTYPE ] [ -i ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -t ] [ -v ] nom-fichier nom-utilisateur

htdbm -b [ -TDBTYPE ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -t ] [ -v ] nom-fichier nom-utilisateur mot-de-passe

htdbm -n [ -i ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -t ] [ -v ] nom-utilisateur

htdbm -nb [ -c ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -t ] [ -v ] nom-utilisateur mot-de-passe

htdbm -v [ -TDBTYPE ] [ -i ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -t ] [ -v ] nom-fichier nom-utilisateur

htdbm -vb [ -TDBTYPE ] [ -c ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -t ] [ -v ] nom-fichier nom-utilisateur mot-de-passe

htdbm -x [ -TDBTYPE ] nom-fichier nom-utilisateur

htdbm -l [ -TDBTYPE ]

Options

-b
Utilise le mode batch ; en d'autres termes, le mot de passe est extrait de la ligne de commande au lieu d'être demandé à l'opérateur. Cette option doit être utilisée avec la plus grande prudence, car le mot de passe est visible en clair dans la ligne de commande. Pour utiliser un script, voir l'option -i.
-i
Lit le mot de passe depuis stdin sans vérification (à utiliser dans le cadre d'un script).
-c
Crée le fichier-mots-de-passe. Si fichier-mots-de-passe existe déjà, il est réécrit et tronqué. Cette option ne peut pas être combinée avec l'option -n.
-n
Affiche les résultats sur la sortie standard et ne met pas à jour la base de données. Cette option modifie la syntaxe de la ligne de commande, car l'argument fichier-mots-de-passe (en général le premier) est omis. Elle ne peut pas être combinée avec l'option -c.
-m
Utilise un chiffrement MD5 pour les mots de passe. Sous Windows et Netware, c'est l'option par défaut..
-B
Utilise l'algorythme de chiffrement bcrypt pour les mots de passe. C'est un algorythme actuellement considéré comme sûr.
-C
Ce drapeau n'est autorisé qu'en conjonction avec le drapeau -B (chiffrement bcrypt). Il permet de définir la durée de traitement pour l'algorythme de chiffrement bcrypt (plus elle est longue, plus la sécurité est élevée, mais la rapidité est diminuée d'autant) ; la valeur par défaut est 5, les valeurs valides vont de 4 à 31.
-d
Utilise un chiffrement crypt() pour les mots de passe. C'est l'option par défaut sur toutes les plates-formes, sauf Windows et Netware. Bien que htdbm supporte ce chiffrement sur toutes les plates-formes, il n'est pas supporté par le serveur httpd sous Windows et Netware. Cet algorythme est considéré comme non sûr selon les standards actuels.
-s
Utilise le chiffrement SHA pour les mots de passe. Facilite la migration vers/depuis les serveurs Netscape qui utilisent le format LDAP Directory Interchange (ldif). Cet algorythme est considéré comme non sûr selon les standards actuels.
-p
Utilise des mots de passe au format texte en clair. Bien que htdbm supporte ce format sur toutes les plates-formes, le démon httpd n'accepte les mots de passe au format texte en clair que sous Windows et Netware.
-l
Affiche chaque nom d'utilisateur de la base de données accompagné de son commentaire sur la sortie standard.
-v
Vérifie une association nom d'utilisateur/mot de passe. Le programme affichera un message indiquant si le mot de passe fourni est valide. Si le mot de passe n'est pas valide, le programme s'arrête et renvoie un code d'erreur 3.
-x
Supprime l'utilisateur. Si le nom d'utilisateur existe dans le fichier DBM spécifié, il sera supprimé.
-t
Interprète le dernier paramètre en tant que commentaire. Avec cette option, il est possible d'ajouter une chaîne supplémentaire à la fin de la ligne de commande ; le contenu de cette chaîne sera stocké dans la base de données dans le champ "Comment" associé au nom d'utilisateur spécifié.
nom-fichier
Le nom du fichier au format DBM en général sans l'extension .db, .pag, ou .dir. Avec l'option -c, le fichier DBM est mis à jour s'il existe ou créé dans le cas contraire.
nom-utilisateur
Le nom d'utilisateur à créer ou mettre à jour dans le fichier-mots-de-passe. Si nom-utilisateur n'existe pas dans ce fichier, une entrée est ajoutée. S'il existe, son mot de passe est modifié.
mot-de-passe
Le mot de passe en clair destiné à être chiffré et stocké dans le fichier DBM. Ne s'utilise qu'avec l'option -b.
-TDBTYPE
Type de fichier DBM (SDBM, GDBM, DB, ou "default").

Bugs

Vous devez garder à l'esprit qu'il existe de nombreux formats de fichiers DBM différents, et que selon toute vraisemblance, des bibliothèques pour plus d'un format sont présentes sur votre système. Les trois exemples de base sont SDBM, NDBM, le projet GNU GDBM, et Berkeley/Sleepycat DB 2/3/4. Malheureusement, toutes ces bibliothèques utilisent des formats de fichiers différents, et vous devez vous assurer que le format de fichier utilisé par nom-fichier correspond au format attendu par htdbm. Actuellement, htdbm n'a aucun moyen de savoir à quel type de fichier DBM il a à faire. S'il est utilisé avec un format inapproprié, il ne renverra rien, ou pourra créer un fichier DBM différent avec un nom différent, ou au pire, va corrompre le fichier DBM si vous avez tenté de le modifier.

Vous pouvez utiliser le programme file fourni par la plupart des systèmes Unix pour déterminer le format d'un fichier DBM.

Valeur renvoyée

htdbm renvoie 0 ("true") si les nom d'utilisateur et mot de passe ont été créés ou mis à jour avec succès dans le fichier DBM. htdbm renvoie 1 s'il a rencontré un problème d'accès aux fichiers, 2 si la ligne de commande comportait une erreur de syntaxe, 3 si le mot de passe a été fourni interactivement et s'il est invalide pour l'entrée considérée, 4 si l'opération a été interrompue, 5 si une valeur est trop longue (nom utilisateur, nom fichier, mot de passe, ou l'enregistrement après son élaboration), 6 si le nom d'utilisateur contient des caractères illégaux (voir la section Restrictions), et 7 si le fichier n'est pas un fichier de mots de passe DBM valide.

Exemples

htdbm /usr/local/etc/apache/.utilisateurs-htdbm jsmith

Ajoute ou modifie le mot de passe de l'utilisateur jsmith. Le mot de passe est demandé à l'opérateur. Sous Windows, le mot de passe sera chiffré en utilisant l'algorithme MD5 Apache modifié ; dans les autres cas, c'est la routine crypt() du système qui sera utilisée. Si le fichier n'existe pas, htdbm s'arrêtera et renverra une erreur.

htdbm -c /home/doe/public_html/.htdbm jane

Crée un nouveau fichier et y enregistre une entrée pour l'utilisateur jane. Le mot de passe est demandé à l'opérateur. Si le fichier existe et ne peut pas être lu, ou ne peut pas être écrit, il ne sera pas modifié et htdbm affichera un message et renverra un code d'erreur.

htdbm -mb /usr/web/.htdbm-tous jones Pwd4Steve

Chiffre le mot de passe entré avec la ligne de commande (Pwd4Steve) à l'aide de l'algorithme MD5, et l'enregistre dans le fichier spécifié.

Considérations à propos de sécurité

Les fichiers de mots de passe Web tels que ceux que gère htdbm ne doivent pas être stockés dans l'espace d'URI du serveur Web -- en d'autres termes, il ne doit pas être possible d'y accéder à l'aide d'un navigateur.

L'utilisation de l'option -b est déconseillée, car lorsqu'il est utilisé, le mot de passe apparaît en clair dans la ligne de commande.

Notez que lorsque vous utilisez l'algorythme crypt(), seuls les 8 premiers caractères du mot de passe sont pris en compte. Si le mot de passe fourni est plus long, les caractères supplémentaires seront ignorés sans avertissement.

L'algorythme SHA ne permet pas de spécifier une valeur d'initialisation pour la génération de nombres aléatoires (salting) : un mot de passe donné ne possède ainsi qu'une réprésentation chiffrée. Les algorythmes crypt() et MD5 permettent quant à eux des représentations chiffrées multiples en acceptant comme paramètre une chaîne d'initialisation (salt), rendant les attaques à base de dictionnaires contre les mots de passe plus difficiles.

Les algorythmes SHA et crypt() sont considérés comme non sûrs selon les standards actuels.

Restrictions

Sur la plate-forme Windows, les mots de passe chiffrés avec htdbm ont une taille limitée à 255 caractères. Si le mot de passe fourni est plus long, il sera tronqué à 255 caractères.

L'algorithme MD5 utilisé par htdbm est spécifique à Apache ; les mots de passe chiffrés en utilisant cet algorithme seront inutilisables sur d'autres serveurs Web.

Les noms d'utilisateurs ont une taille limitée à 255 octets et ne doivent pas contenir de caractère :.


htdigest - Gestion des fichiers d'utilisateurs pour l'authentification à base de condensés - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

htdigest - Gestion des fichiers d'utilisateurs pour l'authentification à base de condensés

htdigest permet de créer et maintenir les fichiers textes dans lesquels sont stockés des noms d'utilisateurs, des domaines de protection (realms) et des mots de passe pour l'authentification à base de condensés des utilisateurs HTTP. L'accès aux ressources du serveur HTTP Apache peut être limité aux seuls utilisateurs enregistrés dans les fichiers créés par htdigest.

Cette page de manuel ne décrit que les arguments de la ligne de commande. Pour plus de détails à propos des directives nécessaires à la configuration de l'authentification à base de condensés dans httpd, voir le manuel Apache qui est fourni avec la distribution et peut être consulté à http://httpd.apache.org/.

Voir aussi

  • httpd
  • mod_auth_digest

Syntaxe

htdigest [ -c ] fichier-mots-de-passe realm nom-utilisateur

options

-c
Crée le fichier fichier-mots-de-passe. Si fichier-mots-de-passe existe déjà, il est tout d'abord supprimé.
fichier-mots-de-passe
Nom du fichier contenant les noms utilisateurs, realms et mots de passe. Si l'option -c est spécifiée, le fichier est créé s'il n'existe pas, ou supprimé et recréé s'il existe déjà.
realm
Le nom du domaine de protection auquel le nom d'utilisateur appartient. Voir http://tools.ietf.org/html/rfc2617#section-3.2.1 pour plus de détails.
nom-utilisateur
Le nom d'utilisateur à créer ou mettre à jour dans le fichier-mots-de-passe. Si nom-utilisateur est absent de ce fichier, une nouvelle entrée est ajoutée. Si l'utilisateur existe déjà, le mot de passe est modifié.

Considérations à propos de sécurité

En tant qu'exécutable setuid, ce programme n'est pas sûr. En conséquence, évitez de lui attribuer des permissions setuid.


htpasswd - Gestion des fichiers d'utilisateurs pour l'authentification de base - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

htpasswd - Gestion des fichiers d'utilisateurs pour l'authentification de base

htpasswd permet de créer et de maintenir les fichiers textes où sont stockés les noms d'utilisateurs et mots de passe pour l'authentification de base des utilisateurs HTTP. Si htpasswd rencontre un problème d'accès à un fichier, que ce soit pour écrire dans le fichier de sortie, ou pour lire le fichier d'entrée dans le but de le mettre à jour, il renvoie un code d'erreur et n'effectue aucune modification.

Il est possible de limiter l'accès aux ressources du serveur HTTP Apache aux seuls utilisateurs présents dans les fichiers créés par htpasswd. Ce programme ne sait gérer les noms d'utilisateurs et mots de passe que s'ils sont stockés dans des fichiers textes. Il peut cependant chiffrer et afficher les mots de passe à des fins d'utilisation dans d'autres types de bases de données. Pour utiliser une base de données DBM, voir le programme dbmmanage ou htdbm.

htpasswd chiffre les mots de passe en utilisant soit bcrypt, une version de MD5 modifiée pour Apache, soit SHA1, soit la routine crypt() du système. Les fichiers gérés par htpasswd peuvent contenir deux types de mots de passe ; certaines entrées peuvent contenir des mots de passe chiffrés en MD5 ou bcrypt, alors que d'autres entrées du même fichier contiendront des mots de passe chiffrés avec crypt().

Cette page de manuel ne décrit que les arguments de la ligne de commande. Pour plus de détails à propos des directives nécessaires à la configuration de l'authentification des utilisateurs dans httpd, voir le manuel Apache qui est fourni avec la distribution ou peut être consulté à http://httpd.apache.org/.

Voir aussi

  • httpd
  • htdbm
  • Les scripts fournis avec la distibution d'Apache et situés dans support/SHA1.

Syntaxe

htpasswd [ -c ] [ -i ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -D ] [ -v ] fichier-mots-de-passe nom-utilisateur

htpasswd -b [ -c ] [ -m | -B | -d | -s | -p ] [ -C cost ] [ -D ] [ -v ] fichier-mots-de-passe nom-utilisateur mot-de-passe

htpasswd -n [ -i ] [ -m | -B | -d | -s | -p ] [ -C cost ] nom-utilisateur

htpasswd -nb [ -m | -B | -d | -s | -p ] [ -C cost ] nom-utilisateur mot-de-passe

Options

-b
Utilise le mode batch ; c'est à dire, extrait le mot de passe de la ligne de commande au lieu de le demander à l'opérateur. Cette option doit être utilisée avec la plus grande prudence, car le mot de passe est visible en clair dans la ligne de commande. Pour utiliser un script, voir l'option -i. Disponible à partir de la version 2.4.4 du serveur HTTP Apache.
-i
Lit le mot de passe depuis stdin sans vérification (à utiliser dans les scripts).
-c
Crée le fichier-mots-de-passe. Si fichier-mots-de-passe existe déjà, il est réécrit et tronqué. Cette option ne peut pas être combinée avec l'option -n.
-n
Affiche le résultat du traitement sur la sortie standard au lieu de mettre à jour le fichier. Ceci peut s'avérer utile pour générer des enregistrements de mots de passe qu'Apache pourra utiliser à des fins d'inclusion dans des fichiers de données au format autre que texte. Cette option modifie la syntaxe de la ligne de commande, car l'argument fichier-mots-de-passe (en général le premier) est omis. Elle ne peut pas être combinée avec l'option -c option.
-m
Utilise le chiffrement MD5 pour les mots de passe. C'est le comportement par défaut (depuis la version 2.2.18).
-B
Utilise bcrypt pour chiffrer les mots de passe. c'est un algorythme de chiffrement actuellement considéré comme sûr.
-C
Ce drapeau n'est autorisé qu'en conjonction avec le drapeau -B (chiffrement bcrypt). Il permet de définir la durée de traitement pour l'algorytme bcrypt (plus elle est longue, meilleure sera la sécurité, mais inférieure la rapidité). La valeur par défaut est 5 et les valeurs autorisées vont de 4 à 31.
-d
Utilise le chiffrement crypt() pour les mots de passe. Cette option n'est pas supportée par le serveur httpd sous Windows ou Netware. Cet algorithme limite la longueur des mots de passe à 8 caractères ; il est considéré comme non sur du point de vue des standards actuels. C'était l'algorithme par défaut jusqu'à la version 2.2.17.
-s
Utilise le chiffrement SHA pour les mots de passe. Facilite la migration vers/depuis les serveurs Netscape qui utilisent le format LDAP Directory Interchange (ldif). Cet algorithme est considéré comme non sur du point de vue des standards actuels.
-p
Enregistre les mots de passe en clair. Bien que htpasswd supporte la création des mots de passe en clair sur toutes les plates-formes, le démon httpd n'accepte les mots de passe en clair que sous Windows et Netware.
-D
Supprime un utilisateur, sous réserve qu'il existe dans le fichier spécifié par htpasswd.
-v
Vérifie si le mot de passe fourni correspond au mot de passe de l'utilisateur enregistré dans le fichier de mots de passe spécifié. Disponible à partir de la version 2.4.5 du serveur HTTP Apache.
fichier-mots-de-passe
Le nom du fichier contenant les noms d'utilisateurs et mots de passe. Avec l'option -c, le fichier est créé s'il n'existe pas, ou réécrit et tronqué s'il existe déjà.
nom-utilisateur
Le nom d'utilisateur à créer ou mettre à jour dans le fichier-mots-de-passe. Si nom-utilisateur n'existe pas, une nouvelle entrée est ajoutée. Dans le cas contraire, le mot de passe est modifié.
mot-de-passe
Le mot de passe en clair et destiné à être chiffré puis stocké dans le fichier. Cet argument ne s'utilise qu'avec l'option -b.

Valeur renvoyée

htpasswd renvoie 0 ("true") si le nom d'utilisateur et le mot de passe ont été enregistrés ou mis à jour avec succès dans le fichier-mots-de-passe. htpasswd renvoie 1 s'il a rencontré un problème d'accès aux fichiers, 2 si la ligne de commande comportait une erreur de syntaxe, 3 si le mot de passe entré interactivement ne correspondait pas au nom d'utilisateur, 4 si l'opération a été interrompue, 5 si une valeur était trop longue (nom-utilisateur, nom-fichier, mot-de-passe, ou l'enregistrement résultant), 6 si le nom d'utilisateur contenait des caractères illégaux (voir la section Restrictions), et 7 si le fichier spécifié n'était pas un fichier de mots de passe valide.

Exemples

htpasswd /usr/local/etc/apache/.utilisateurs-htpasswd jsmith

Ajoute ou modifie le mot de passe de l'utilisateur jsmith. Le mot de passe est demandé à l'opérateur. Le mot de passe sera chiffré en utilisant l'algorithme MD5 modifié pour Apache. Si le fichier spécifié n'existe pas, htpasswd renverra un code d'erreur.

htpasswd -c /home/doe/public_html/.htpasswd jane

Crée un nouveau fichier de mots de passe et y enregistre une entrée pour l'utilisateur jane. Le mot de passe est demandé à l'opérateur. Si le fichier existe et ne peut être ni lu ni écrit, il n'est pas modifié et htpasswd affichera un message et renverra un code d'erreur.

htpasswd -db /usr/web/.htpasswd-tous jones Pwd4Steve

Chiffre le mot de passe spécifié dans la ligne de commande (Pwd4Steve) en utilisant l'algorithme crypt(), et le stocke dans le fichier spécifié.

Considérations à propos de sécurité

Les fichiers de mots de passe Web comme ceux que gère htpasswd ne doivent pas être situés dans l'espace d'URI du serveur Web -- en d'autres termes, il ne doit pas être possible d'y accéder à partir d'un navigateur.

En tant qu'exécutable setuid, ce programme n'est pas sûr, et il ne faut par conséquent pas lui attribuer de permissions setuid.

L'utilisation de l'option -b est déconseillée, car avec elle, les mots de passe apparaissent en clair dans la ligne de commande.

Notez qu'avec l'algorithme crypt(), seuls les huit premiers caractères du mot de passe spécifié sont pris en compte. Si le mot de passe spécifié est plus long, les caractères supplémentaires sont ignorés.

Le format de chiffrement SHA n'utilise pas d'amorçage aléatoire (salting) : à un mot de passe donné correspond une seule représentation chiffrée. Les formats crypt() et MD5 permutent la représentation en la préfixant par une chaîne d'amorce aléatoire, afin de rendre les attaques de mots de passe à base de dictionnaires plus difficiles.

Les algorithmes de chiffrement SHA et crypt() sont considérés comme non surs du point de vue des standards actuels.

Restrictions

Sur les plates-formes Windows, la taille des mots de passe chiffrés avec htpasswd est limitée à 255 caractères. Les mots de passe dont la taille est supérieure seront tronqués.

L'algorithme MD5 utilisé par htpasswd est spécifique à Apache ; les mots de passe chiffrés en utilisant cet algorithme seront inutilisables sur d'autres serveurs Web.

La taille des noms d'utilisateurs est limitée à 255 octets et ceux-ci ne doivent pas contenir de caractère :.


httxt2dbm - Génère des fichiers dbm à utiliser avec RewriteMap - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

httxt2dbm - Génère des fichiers dbm à utiliser avec RewriteMap

httxt2dbm permet, à partir d'une entrée au format texte, de générer des fichiers dbm à utiliser dans les directives RewriteMap avec le type de table dbm.

Si le fichier de sortie existe déjà, il ne sera pas tronqué. Les nouvelles clés seront ajoutées et les clés préexistantes mises à jour.

Voir aussi

  • httpd
  • mod_rewrite

Syntaxe

httxt2dbm [ -v ] [ -f TYPE_DBM ] -i TEXTE_SOURCE -o SORTIE_DBM

Options

-v
Sortie plus verbeuse
-f TYPE_DBM
Spécifie le type DBM à utiliser pour le fichier de sortie. S'il n'est pas spécifié, c'est la valeur par défaut de l'APR qui sera utilisée. Les types disponibles sont : GDBM pour les fichiers GDBM, SDBM pour les fichiers SDBM, DB pour les fichiers DB, NDBM pour les fichiers NDBM, default pour le type DBM par défaut
-i TEXTE_SOURCE
Le fichier d'entrée à partir duquel le fichier dbm sera créé. Le fichier doit être formaté de façon à ne contenir qu'un seul enregistrement par ligne, de la forme : clé valeur. Voir la documentation de la directive RewriteMap pour plus de détails à propos du format de ce fichier et de sa signification.
-o SORTIE_DBM
Nom du fichier dbm de sortie.

Exemples

httxt2dbm -i rewritemap.txt -o rewritemap.dbm
httxt2dbm -f SDBM -i rewritemap.txt -o rewritemap.dbm


logresolve - Résoud les adresses IP en noms d'hôtes dans les fichiers journaux d'Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

logresolve - Résoud les adresses IP en noms d'hôtes dans les fichiers journaux d'Apache

logresolve est un programme agissant après traitement pour résoudre les adresses IP dans les journaux d'accès d'Apache. Pour minimiser la charge de votre serveur de noms, logresolve possède son propre cache interne sous forme d'une table de hashage. Cela implique que chaque numéro IP ne fera l'objet d'une requête DNS que la première fois où il est rencontré dans le fichier journal.

Le programme reçoit le fichier journal sur son entrée standard. Les adresses IP doivent se trouver en tête de chaque ligne et doivent être séparées du reste de la ligne par un espace.

Syntaxe

logresolve [ -s nom-fichier ] [ -c ] < access_log > access_log.new

Options

-s nom-fichier
Spécifie le nom du fichier où seront enregistrées des statistiques.
-c
Avec cette option, logresolve effectue certaines vérifications DNS : après avoir trouvé le nom d'hôte correspondant à une adresse IP, logresolve effectue une recherche DNS sur ce nom d'hôte et vérifie si une des adresses IP trouvées correspond à l'adresse originale.


log_server_status - Log periodic status summaries - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Programs

log_server_status - Log periodic status summaries

This perl script is designed to be run at a frequent interval by something like cron. It connects to the server and downloads the status information. It reformats the information to a single line and logs it to a file. Adjust the variables at the top of the script to specify the location of the resulting logfile. mod_status will need to be loaded and configured in order for this script to do its job.

Usage

The script contains the following section.

my $wherelog = "/usr/local/apache2/logs/";  # Logs will be like "/usr/local/apache2/logs/19960312"
my $server   = "localhost";        # Name of server, could be "www.foo.com"
my $port     = "80";               # Port on server
my $request = "/server-status/?auto";    # Request to send

You'll need to ensure that these variables have the correct values, and you'll need to have the /server-status handler configured at the location specified, and the specified log location needs to be writable by the user which will run the script.

Run the script periodically via cron to produce a daily log file, which can then be used for statistical analysis.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


rotatelogs - Rotation des journaux d'Apache par redirection de ces derniers dans un "pipe" - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

rotatelogs - Rotation des journaux d'Apache par redirection de ces derniers dans un "pipe"

rotatelogs est un programme simple à utiliser en conjonction avec la fonctionnalité d'Apache de redirection dans un "pipe" des fichiers journaux. Il supporte une rotation basée sur un intervalle de temps ou une taille maximale du journal.

Syntaxe

rotatelogs
     [ -l ]
     [ -L nom-lien ]
     [ -p programme ]
     [ -f ]
     [ -t ]
     [ -v ]
     [ -e ]
     [ -c ]
     [ -n nombre-de-fichiers ]
     fichier-journal
     heure-de-rotation|taille-fichier(B|K|M|G)
     [ décalage ]

Options

-l
Utilise le temps local plutôt que GMT comme base pour l'intervalle de temps ou pour le formatage de strftime(3) avec une rotation basée sur la taille.
-L nom-lien
Etablit un lien physique entre le fichier journal courant et le lien spécifié. Cette option permet de consulter le journal de manière continue malgré les rotations via une commande du style tail -F nom-lien.
-p programme
Avec cette option, rotatelogs exécutera le programme programme chaque fois qu'un nouveau fichier journal sera ouvert. Le nom du fichier nouvellement ouvert est passé comme premier argument au programme. Si l'exécution se produit après une rotation, l'ancien nom du fichier journal est passé au programme comme second argument. rotatelogs n'attend pas la fin du programme pour continuer son exécution, et cessera tout enregistrement de codes d'erreur lorsqu'il aura terminé son processus. Le programme utilise les mêmes canaux stdin, stdout, et stderr que rotatelogs, et hérite de son environnement.
-f
Ouvre le fichier journal immédiatement, dès que rotatelogs démarre, au lieu d'attendre la lecture de la première entrée de journal (pour les sites peu chargés, il peut s'écouler un temps substantiel entre le démarrage du serveur et le traitement de la première requête, temps pendant lequel le fichier journal associé n'"existe" pas, ce qui peut causer des problèmes à certains utilitaires de journalisation automatiques).
-t
Provoque une troncature du fichier journal au lieu d'une rotation. Cela peut s'avérer utile lorsqu'un journal est élaboré en temps réel par une commande telle que tail, l'archivage des données n'étant ici pas nécessaire. Si aucun suffixe n'est ajouté au nom de fichier, les chaînes de format contenant des caractères '%' sont cependant respectées.
-v
Affiche une sortie verbeuse sur STDERR. La sortie contient le résultat de l'interprétation de la configuration, ainsi que toutes les opérations d'ouverture et de fermeture de fichiers.
-c
Crée un fichier journal pour chaque intervalle, même s'il est vide.
-e
Envoie les messages de journalisation vers stdout. Ceci s'avère utile lorsque les journaux doivent être traités par un autre programme.
-n nombre-de-fichiers
Utilise une liste circulaire de fichiers sans repères de temps. Avec -n 3, la série de fichiers conservés sera "logfile", "logfile.1", "logfile.2" avec écrasement de "logfile". Disponible à partir de la version 2.4.5 du serveur HTTP Apache.
fichier-journal

Le chemin et le nom de base du fichier journal. Si fichier-journal contient des caractères '%', il est considéré comme une chaîne de formatage pour strftime(3). Dans le cas contraire, le suffixe .nnnnnnnnnn est automatiquement ajouté et correspond au temps en secondes (sauf si l'option -t est spécifiée). Les deux formats calculent le temps de démarrage depuis le début de la période courante. Par exemple, si un temps de rotation de 86400 est spécifié, les champs heure, minute et seconde créés à partir du format strftime(3) auront tous pour valeur 0, en référence au début de la période de 24 heures courante (minuit).

Si vous utilisez le formatage de noms de fichiers strftime(3), assurez-vous que le format du fichier journal possède une granularité suffisamment importante pour générer un nom de fichier différent à chaque rotation des journaux. Si ce n'est pas le cas, la rotation va écraser le fichier existant au lieu d'en générer un nouveau. Par exemple, si fichier-journal était /var/log/errorlog.%Y-%m-%d avec une rotation à 5 mégaoctets, et si la limite de 5 mégaoctets a été atteinte deux fois dans la même journée, le même nom de fichier va être généré, et la rotation va écraser le fichier existant.

temps-rotation
Le temps entre deux rotations des fichiers journaux en secondes. La rotation intervient au début de cet intervalle. Par exemple, si le temps de rotation est de 3600, la rotation des fichiers journaux s'effectuera au début de chaque heure ; si le temps de rotation est de 86400, la rotation des fichiers journaux s'effectuera chaque nuit à minuit. (Si aucune donnée n'est enregistrée au cours d'un intervalle, aucun fichier ne sera créé).
taille-fichier(B|K|M|G)
La taille maximale du fichier suivie par une des lettres B (Octets), K (KOctets), M (MOctets) ou G (GOctets).

Lorsque temps et taille sont spécifiés, la taille doit l'être après le temps. La rotation interviendra alors aussitôt que l'une des deux limites (temps ou taille) sera atteinte.

décalage
Le décalage en minutes par rapport au temps UTC. Par défaut, le décalage est considéré comme nul et c'est le temps UTC qui est utilisé. Par exemple, pour utiliser le temps local de la zone UTC -5 heures, spécifiez une valeur de -300 pour cette option. Dans la plupart des cas, il vaut mieux utiliser l'option -l que spécifier un décalage.

Exemples

CustomLog "|bin/rotatelogs /var/log/fichier-journal 86400" common

Cette directive crée les fichiers /var/log/fichier-journal.nnnn où nnnn correspond au temps système auquel la journalisation démarre effectivement (ce temps sera toujours un multiple du temps de rotation, si bien que vous pouvez synchroniser les scripts cron avec lui). A la fin de chaque temps de rotation (ici après 24 heures), une nouvelle journalisation démarre.

CustomLog "|bin/rotatelogs -l /var/log/fichier-journal.%Y.%m.%d 86400" common

Cette directive crée les fichiers /var/log/fichier-journal.yyyy.mm.dd où yyyy correspond à l'année, mm au mois et dd au jour du mois. La journalisation basculera vers un nouveau fichier chaque jour à minuit, temps local.

CustomLog "|bin/rotatelogs /var/log/fichier-journal 5M" common

Cette directive va effectuer une rotation du fichier journal chaque fois que la taille de ce dernier atteindra 5 MOctets.

ErrorLog "|bin/rotatelogs /var/log/journal-erreurs.%Y-%m-%d-%H_%M_%S 5M"

Cette directive va effectuer une rotation du fichier journal des erreurs chaque fois que la taille de ce dernier atteindra 5 MOctets, et le nom du fichier journal se présentera sous la forme journal-erreurs.YYYY-mm-dd-HH_MM_SS.

CustomLog "|bin/rotatelogs -t /var/log/journal 86400" common

Cet exemple crée le fichier /var/log/journal en le tronquant au démarrage, puis une fois par jour. Ce scénario implique qu'un processus séparé (tel que tail) traite le fichier en temps réel.

Portabilité

Les substitutions des chaînes de format du fichier journal suivantes doivent être supportées par toutes les implémentations de strftime(3) ; voir la page de manuel de strftime(3) pour les extensions spécifiques à une bibliothèque.

%A | nom du jour de la semaine en entier (localisé)
%a | nom du jour de la semaine sur 3 caractères (localisé)
%B | nom du mois en entier (localisé)
%b | nom du mois sur 3 caractères (localisé)
%c | date et heure (localisé)
%d | jour du mois sur 2 chiffres
%H | heure sur 2 chiffres (de 0 à 24h)
%I | heure sur 2 chiffres (de 0 à 12h)
%j | jour de l'année sur 3 chiffres
%M | minutes sur 2 chiffres
%m | mois sur 2 chiffres
%p | suffixe am/pm pour l'heure de 0 à 12h (localisé)
%S | secondes sur 2 chiffres
%U | semaine de l'année sur 2 chiffres (Dimanche est le premier jour de la semaine)
%W | semaine de l'année sur 2 chiffres (Lundi est le premier jour de la semaine)
%w | jour de la semaine sur 1 chiffre (Dimanche est le premier jour de la semaine)
%X | heure (localisée)
%x | date (localisée)
%Y | année sur 4 chiffres
%y | année sur 2 chiffres
%Z | nom de la zone de temps
%% | caractère littéral `%'


split-logfile - Split up multi-vhost logfiles - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Programs

split-logfile - Split up multi-vhost logfiles

This perl script will take a combined Web server access log file and break its contents into separate files. It assumes that the first field of each line is the virtual host identity, put there using the "%v" variable in LogFormat.

Usage

Create a log file with virtual host information in it:

LogFormat "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined_plus_vhost
CustomLog logs/access_log combined_plus_vhost

Log files will be created, in the directory where you run the script, for each virtual host name that appears in the combined log file. These logfiles will named after the hostname, with a .log file extension.

The combined log file is read from stdin. Records read will be appended to any existing log files.

split-logfile < access_log

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


suexec - Switch user before executing external programs - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Programs

suexec - Switch user before executing external programs

suexec is used by the Apache HTTP Server to switch to another user before executing CGI programs. In order to achieve this, it must run as root. Since the HTTP daemon normally doesn't run as root, the suexec executable needs the setuid bit set and must be owned by root. It should never be writable for any other person than root.

For further information about the concepts and the security model of suexec please refer to the suexec documentation (http://httpd.apache.org/docs/2.4/suexec.html).

Synopsis

suexec -V

Options

-V
If you are root, this option displays the compile options of suexec. For security reasons all configuration options are changeable only at compile time.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Autres programmes - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Programmes

Autres programmes

Cette page contenait la documentation de programmes qui possèdent maintenant leurs propres pages de documentation. Merci de bien vouloir mettre à jour vos liens.

log_server_status

split-logfile


Documentations diverses sur Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Documentations diverses sur Apache

Vous trouverez plus loin une liste de pages de documentation additionnelles concernant le projet de développement du serveur web Apache.

Avertissement

La mise à jour des documents ci-dessous permettant de prendre en compte les modifications apportées par la version 2.1 du serveur HTTP Apache n'a pas été entièrement menée à bien. Certaines informations sont probablement encore pertinentes, mais utilisez-les tout de même avec précautions.

Notes à propos des performances - Réglages fins d'Apache

Notes à propos de la configuration d'Apache pour de plus hautes performances (à l'exécution et à la compilation). Notes expliquant pourquoi Apache accomplit certaines choses et n'en accomplit pas certaines autres (les premières l'accélérant et les deuxièmes le ralentissant).

Conseils concernant la sécurité

Quelques conseils de type "faites" ou "ne faites pas" pour que votre site web Apache reste sécurisé.

Standards concernés

Ce document constitue une page de référence pour la plupart des standards concernés par Apache.

Formats de chiffrement des mots de passe

Discussion à propos des divers algorithmes de chiffrement supportés par Apache à des fins d'authentification.


Optimisation des performances d'Apache - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Documentations diverses

Optimisation des performances d'Apache

Apache 2.x est un serveur web à usage général, conçu dans un but d'équilibre entre souplesse, portabilité et performances. Bien que non conçu dans le seul but d'établir une référence en la matière, Apache 2.x est capable de hautes performances dans de nombreuses situations du monde réel.

Comparée à Apache 1.3, la version 2.x comporte de nombreuses optimisations supplémentaires permettant d'améliorer le débit du serveur et sa personnalisation. La plupart de ces améliorations sont activées par défaut. Cependant, certains choix de configuration à la compilation et à l'exécution peuvent affecter les performances de manière significative. Ce document décrit les options qu'un administrateur de serveur peut configurer pour améliorer les performances d'une installation d'Apache 2.x. Certaines de ces options de configuration permettent au démon httpd de mieux tirer parti des possibilités du matériel et du système d'exploitation, tandis que d'autres permettent à l'administrateur de privilégier la vitesse par rapport aux fonctionnalités.

Problèmes matériels et relatifs au système d'exploitation

Le principal problème matériel qui affecte les performances du serveur web est la mémoire vive (RAM). Un serveur web ne devrait jamais avoir à utiliser le swap, car le swapping augmente le temps de réponse de chaque requête au delà du point que les utilisateurs considèrent comme "trop lent". Ceci incite les utilisateurs à cliquer sur "Stop", puis "Charger à nouveau", ce qui a pour effet d'augmenter encore la charge du serveur. Vous pouvez, et même devez définir la valeur de la directive MaxRequestWorkers de façon à ce que votre serveur ne lance pas un nombre de processus enfants tel qu'il commence à faire du swapping. La méthode pour y parvenir est simple : déterminez la taille de votre processus Apache standard en consultant votre liste de processus à l'aide d'un outil tel que top, et divisez votre quantité totale de mémoire disponible par cette taille, tout en gardant un espace suffisant pour les autres processus.

Hormis ce réglage relatif à la mémoire, le reste est trivial : le processeur, la carte réseau et les disques doivent être suffisamment rapides, où "suffisamment rapide" doit être déterminé par l'expérience.

Le choix du système d'exploitation dépend principalement du contexte local. Voici cependant quelques conseils qui se sont généralement avérés utiles :

  • Exécutez la dernière version stable et le niveau de patches le plus haut du système d'exploitation que vous avez choisi. De nombreux éditeurs de systèmes d'exploitation ont amélioré de manière significative les performances de leurs piles TCP et de leurs bibliothèques de thread ces dernières années.

  • Si votre système d'exploitation possède un appel système sendfile(2), assurez-vous d'avoir installé la version et/ou les patches nécessaires à son activation. (Pour Linux, par exemple, cela se traduit par Linux 2.4 ou plus. Pour les versions anciennes de Solaris 8, vous pouvez être amené à appliquer un patch.) Sur les systèmes où il est disponible, sendfile permet à Apache 2 de servir les contenus statiques plus rapidement, tout en induisant une charge CPU inférieure.

Optimisation de la configuration à l'exécution

Modules Apparentés Directives Apparentées
  • mod_dir
  • mpm_common
  • mod_status
  • AllowOverride
  • DirectoryIndex
  • HostnameLookups
  • EnableMMAP
  • EnableSendfile
  • KeepAliveTimeout
  • MaxSpareServers
  • MinSpareServers
  • Options
  • StartServers

HostnameLookups et autres considérations à propos du DNS

Avant Apache 1.3, la directive HostnameLookups était positionnée par défaut à On. Ce réglage augmente le temps de réponse de chaque requête car il entraîne une recherche DNS et le traitement de la requête ne pourra pas être achevé tant que cette recherche ne sera pas terminée. Avec Apache 1.3, ce réglage est défini par défaut à Off. Si vous souhaitez que les adresses dans vos fichiers journaux soient résolues en noms d'hôtes, utilisez le programme logresolve fourni avec Apache, ou un des nombreux paquets générateurs de rapports sur les journaux disponibles.

Il est recommandé d'effectuer ce genre de traitement a posteriori de vos fichiers journaux sur une autre machine que celle qui héberge le serveur web en production, afin que cette activité n'affecte pas les performances du serveur.

Si vous utilisez une directive Allowfrom domain ou Deny from domain (ce qui signifie que vous utilisez un nom d'hôte ou un nom de domaine à la place d'une adresse IP), vous devrez compter avec deux recherches DNS (une recherche inverse suivie d'une recherche directe pour s'assurer que l'adresse IP n'a pas été usurpée). C'est pourquoi il est préférable, pour améliorer les performances, d'utiliser des adresses IP plutôt que des noms lorsqu'on utilise ces directives, du moins chaque fois que c'est possible.

Notez qu'il est possible de modifier la portée des directives, en les plaçant par exemple à l'intérieur d'une section <Location "/server-status">. Les recherches DNS ne seront alors effectuées que pour les requêtes qui satisfont aux critères. Voici un exemple qui désactive les recherches DNS sauf pour les fichiers .html et .cgi :

HostnameLookups off
<Files ~ "\.(html|cgi)$">
  HostnameLookups on
</Files>

Mais même dans ce cas, si vous n'avez besoin de noms DNS que dans certains CGIs, vous pouvez effectuer l'appel à gethostbyname dans les CGIs spécifiques qui en ont besoin.

FollowSymLinks et SymLinksIfOwnerMatch

Chaque fois que la ligne Options FollowSymLinks sera absente, ou que la ligne Options SymLinksIfOwnerMatch sera présente dans votre espace d'adressage, Apache devra effectuer des appels système supplémentaires pour vérifier la présence de liens symboliques. Un appel supplémentaire par élément du chemin du fichier. Par exemple, si vous avez :

DocumentRoot "/www/htdocs"
<Directory "/">
  Options SymLinksIfOwnerMatch
</Directory>

et si une requête demande l'URI /index.html, Apache effectuera un appel à lstat(2) pour /www, /www/htdocs, et /www/htdocs/index.html. Les résultats de ces appels à lstat ne sont jamais mis en cache, ils devront donc être générés à nouveau pour chaque nouvelle requête. Si vous voulez absolument vérifier la sécurité des liens symboliques, vous pouvez utiliser une configuration du style :

DocumentRoot "/www/htdocs"
<Directory "/">
  Options FollowSymLinks
</Directory>

<Directory "/www/htdocs">
  Options -FollowSymLinks +SymLinksIfOwnerMatch
</Directory>

Ceci évite au moins les vérifications supplémentaires pour le chemin défini par DocumentRoot. Notez que vous devrez ajouter des sections similaires si vous avez des chemins définis par les directives Alias ou RewriteRule en dehors de la racine de vos documents. Pour améliorer les performances, et supprimer toute protection des liens symboliques, ajoutez l'option FollowSymLinks partout, et n'utilisez jamais l'option SymLinksIfOwnerMatch.

AllowOverride

Dans toute partie de votre espace d'adressage où vous autoriserez la surcharge de la configuration (en général à l'aide de fichiers .htaccess), Apache va tenter d'ouvrir .htaccess pour chaque élément du chemin du fichier demandé. Par exemple, si vous avez :

DocumentRoot "/www/htdocs"
<Directory "/">
  AllowOverride all
</Directory>

et qu'une requête demande l'URI /index.html, Apache tentera d'ouvrir /.htaccess, /www/.htaccess, et /www/htdocs/.htaccess. Les solutions sont similaires à celles évoquées précédemment pour Options FollowSymLinks. Pour améliorer les performances, utilisez AllowOverride None pour tous les niveaux de votre espace d'adressage.

Négociation

Dans la mesure du possible, évitez toute négociation de contenu si vous tenez au moindre gain en performances. En pratique toutefois, les bénéfices de la négociation l'emportent souvent sur la diminution des performances. Il y a cependant un cas dans lequel vous pouvez accélérer le serveur. Au lieu d'utiliser une directive générique comme :

DirectoryIndex index

utilisez une liste explicite d'options :

DirectoryIndex index.cgi index.pl index.shtml index.html

où vous placez le choix courant en première position.

Notez aussi que créer explicitement un fichier de correspondances de type fournit de meilleures performances que l'utilisation des MultiViews, car les informations nécessaires peuvent être simplement obtenues en lisant ce fichier, sans avoir à parcourir le répertoire à la recherche de types de fichiers.

Par conséquent, si la négociation de contenu est nécessaire pour votre site, préférez les fichiers de correspondances de type aux directives Options MultiViews pour mener à bien cette négociation. Se référer au document sur la Négociation de contenu pour une description complète des méthodes de négociation, et les instructions permettant de créer des fichiers de correspondances de type.

Transfert en mémoire

Dans les situations où Apache 2.x doit consulter le contenu d'un fichier en train d'être servi - par exemple à l'occasion du traitement d'une inclusion côté serveur - il transfère en général le fichier en mémoire si le système d'exploitation supporte une forme quelconque de mmap(2).

Sur certains systèmes, ce transfert en mémoire améliore les performances. Dans certains cas, ce transfert peut toutefois les dégrader et même diminuer la stabilité du démon httpd :

  • Dans certains systèmes d'exploitation, mmap devient moins efficace que read(2) quand le nombre de processeurs augmente. Sur les serveurs multiprocesseurs sous Solaris, par exemple, Apache 2.x sert parfois les fichiers consultés par le serveur plus rapidement quand mmap est désactivé.

  • Si vous transférez en mémoire un fichier localisé dans un système de fichiers monté par NFS, et si un processus sur une autre machine cliente NFS supprime ou tronque le fichier, votre processus peut rencontrer une erreur de bus la prochaine fois qu'il essaiera d'accéder au contenu du fichier en mémoire.

Pour les installations où une de ces situations peut se produire, vous devez utiliser EnableMMAP off afin de désactiver le transfert en mémoire des fichiers servis. (Note : il est possible de passer outre cette directive au niveau de chaque répertoire.)

Sendfile

Dans les cas où Apache peut se permettre d'ignorer le contenu du fichier à servir - par exemple, lorsqu'il sert un contenu de fichier statique - il utilise en général le support sendfile du noyau si le système d'exploitation supporte l'opération sendfile(2).

Sur la plupart des plateformes, l'utilisation de sendfile améliore les performances en éliminant les mécanismes de lecture et envoi séparés. Dans certains cas cependant, l'utilisation de sendfile peut nuire à la stabilité du démon httpd :

  • Certaines plateformes peuvent présenter un support de sendfile défaillant que la construction du système n'a pas détecté, en particulier si les binaires ont été construits sur une autre machine et transférés sur la machine où le support de sendfile est défaillant.

  • Dans le cas d'un système de fichiers monté sous NFS, le noyau peut s'avérer incapable de servir les fichiers réseau de manière fiable depuis son propre cache.

Pour les installations où une de ces situations peut se produire, vous devez utiliser EnableSendfile off afin de désactiver la mise à disposition de contenus de fichiers par sendfile. (Note : il est possible de passer outre cette directive au niveau de chaque répertoire.)

Process Creation

Avant Apache 1.3, les directives MinSpareServers, MaxSpareServers, et StartServers avaient des effets drastiques sur les performances de référence. En particulier, Apache avait besoin d'un délai de "montée en puissance" afin d'atteindre un nombre de processus enfants suffisant pour supporter la charge qui lui était appliquée. Après le lancement initial des processus enfants par StartServers, seulement un processus enfant par seconde était créé afin d'atteindre la valeur de la directive MinSpareServers. Ainsi, un serveur accédé par 100 clients simultanés et utilisant la valeur par défaut de 5 pour la directive StartServers, nécessitait environ 95 secondes pour lancer suffisamment de processus enfants permettant de faire face à la charge. Ceci fonctionne en pratique pour les serveurs en production, car ils sont rarement redémarrés. Ce n'est cependant pas le cas pour les tests de référence (benchmarks) où le serveur ne fonctionne que 10 minutes.

La règle "un processus par seconde" avait été implémentée afin d'éviter l'enlisement de la machine dans le démarrage de nouveaux processus enfants. Pendant que la machine est occupée à lancer des processus enfants, elle ne peut pas traiter les requêtes. Mais cette règle impactait tellement la perception des performances d'Apache qu'elle a dû être remplacée. A partir d'Apache 1.3, le code a assoupli la règle "un processus par seconde". Il va en lancer un, attendre une seconde, puis en lancer deux, attendre une seconde, puis en lancer quatre et ainsi de suite jusqu'à lancer 32 processus. Il s'arrêtera lorsque le nombre de processus aura atteint la valeur définie par la directive MinSpareServers.

Ceci s'avère suffisamment réactif pour pouvoir en général se passer de manipuler les valeurs des directives MinSpareServers, MaxSpareServers et StartServers. Lorsque plus de 4 processus enfants sont lancés par seconde, un message est émis vers le journal des erreurs. Si vous voyez apparaître souvent ce genre de message, vous devez vous pencher sur ces réglages. Pour vous guider, utilisez les informations délivrées par le module mod_status.

À mettre en relation avec la création de processus, leur destruction est définie par la valeur de la directive MaxConnectionsPerChild. Sa valeur par défaut est 0, ce qui signifie qu'il n'y a pas de limite au nombre de connexions qu'un processus enfant peut traiter. Si votre configuration actuelle a cette directive réglée à une valeur très basse, de l'ordre de 30, il est conseillé de l'augmenter de manière significative. Si vous utilisez SunOs ou une ancienne version de Solaris, utilisez une valeur de l'ordre de 10000 à cause des fuites de mémoire.

Lorsqu'ils sont en mode "keep-alive", les processus enfants sont maintenus et ne font rien sinon attendre la prochaine requête sur la connexion déjà ouverte. La valeur par défaut de 5 de la directive KeepAliveTimeout tend à minimiser cet effet. Il faut trouver le bon compromis entre la bande passante réseau et les ressources du serveur. En aucun cas vous ne devez choisir une valeur supérieure à 60 seconds, car la plupart des bénéfices sont alors perdus.

Optimisation de la configuration à la compilation

Choisir un Module Multi-Processus (MPM)

Apache 2.x supporte les modèles simultanés enfichables, appelés Modules Multi-Processus (MPMs). Vous devez choisir un MPM au moment de la construction d'Apache. Certaines plateformes ont des modules MPM spécifiques : mpm_netware, mpmt_os2 et mpm_winnt. Sur les systèmes de type Unix, vous avez le choix entre un grand nombre de modules MPM. Le choix du MPM peut affecter la vitesse et l'évolutivité du démon httpd :

  • Le MPM worker utilise plusieurs processus enfants possédant chacun de nombreux threads. Chaque thread gère une seule connexion à la fois. Worker est en général un bon choix pour les serveurs présentant un traffic important car il possède une empreinte mémoire plus petite que le MPM prefork.
  • Comme le MPM Worker, le MPM event utilise les threads, mais il a été conçu pour traiter davantage de requêtes simultanément en confiant une partie du travail à des threads de support, ce qui permet aux threads principaux de traiter de nouvelles requêtes.
  • Le MPM prefork utilise plusieurs processus enfants possédant chacun un seul thread. Chaque processus gère une seule connexion à la fois. Sur de nombreux systèmes, prefork est comparable en matière de vitesse à worker, mais il utilise plus de mémoire. De par sa conception sans thread, prefork présente des avantages par rapport à worker dans certaines situations : il peut être utilisé avec les modules tiers qui ne supportent pas le threading, et son débogage est plus aisé sur les platesformes présentant un support du débogage des threads rudimentaire.

Pour plus d'informations sur ces deux MPMs et les autres, veuillez vous référer à la documentation sur les MPM.

Modules

Comme le contrôle de l'utilisation de la mémoire est très important en matière de performance, il est conseillé d'éliminer les modules que vous n'utilisez pas vraiment. Si vous avez construit ces modules en tant que DSOs, leur élimination consiste simplement à commenter la directive LoadModule associée à ce module. Ceci vous permet de vérifier si votre site fonctionne toujours après la suppression de tel ou tel module.

Par contre, si les modules que vous voulez supprimer sont liés statiquement à votre binaire Apache, vous devrez recompiler ce dernier afin de pouvoir les éliminer.

La question qui découle de ce qui précède est évidemment de savoir de quels modules vous avez besoin et desquels vous pouvez vous passer. La réponse sera bien entendu différente d'un site web à l'autre. Cependant, la liste minimale de modules nécessaire à la survie de votre site contiendra certainement mod_mime, mod_dir et mod_log_config. mod_log_config est bien entendu optionnel puisque vous pouvez faire fonctionner un site web en se passant de fichiers journaux ; ceci est cependant déconseillé.

Opérations atomiques

Certains modules, à l'instar de mod_cache et des versions de développement récentes du MPM worker, utilisent l'API atomique d'APR. Cette API propose des opérations atomiques que l'on peut utiliser pour alléger la synchronisation des threads.

Par défaut, APR implémente ces opérations en utilisant les mécanismes les plus efficaces disponibles sur chaque plateforme cible (Système d'exploitation et processeur). De nombreux processeurs modernes, par exemple, possèdent une instruction qui effectue une opération atomique de type comparaison et échange ou compare-and-swap (CAS) au niveau matériel. Sur certaines platesformes cependant, APR utilise par défaut une implémentation de l'API atomique plus lente, basée sur les mutex, afin d'assurer la compatibilité avec les anciens modèles de processeurs qui ne possèdent pas ce genre d'instruction. Si vous construisez Apache pour une de ces platesformes, et ne prévoyez de l'exécuter que sur des processeurs récents, vous pouvez sélectionner une implémentation atomique plus rapide à la compilation en utilisant l'option --enable-nonportable-atomics du script configure :

./buildconf
./configure --with-mpm=worker --enable-nonportable-atomics=yes

L'option --enable-nonportable-atomics concerne les platesformes suivantes :

  • Solaris sur SPARC
    Sur Solaris/SPARC, APR utilise par défaut les opérations atomiques basées sur les mutex. Cependant, si vous ajoutez l'option --enable-nonportable-atomics au script configure, APR génère un code qui utilise le code opération SPARC v8plus pour des opérations de compare-and-swap matériel plus rapides. Si vous utilisez cette option de configure avec Apache, les opérations atomiques seront plus efficaces (permettant d'alléger la charge du processeur et un plus haut niveau de simultanéité), mais l'exécutable produit ne fonctionnera que sur les processeurs UltraSPARC.
  • Linux sur x86
    Sous Linux, APR utilise par défaut les opérations atomiques basées sur les mutex. Cependant, si vous ajoutez l'option --enable-nonportable-atomics au script configure, APR générera un code qui utilise un code d'opération du 486 pour des opérations de compare-and-swap matériel plus rapides. Le code résultant est plus efficace en matière d'opérations atomiques, mais l'exécutable produit ne fonctionnera que sur des processeurs 486 et supérieurs (et non sur des 386).

Module mod_status et ExtendedStatus On

Si vous incluez le module mod_status à la construction d'Apache et ajoutez ExtendedStatus On à sa configuration, Apache va effectuer pour chaque requête deux appels à gettimeofday(2) (ou times(2) selon votre système d'exploitation), et (pour les versions antérieures à 1.3) de nombreux appels supplémentaires à time(2). Tous ces appels sont effectués afin que le rapport de statut puisse contenir des indications temporelles. Pour améliorer les performances, utilisez ExtendedStatus off (qui est le réglage par défaut).

accept Serialization - points de connexion à un programme (sockets) multiples

Mise en garde :

Cette section n'a pas été totalement mise à jour car elle ne tient pas compte des changements intervenus dans la version 2.x du Serveur HTTP Apache. Certaines informations sont encore pertinentes, il vous est cependant conseillé de les utiliser avec prudence.

Ce qui suit est une brève discussion à propos de l'API des sockets Unix. Supposons que votre serveur web utilise plusieurs directives Listen afin d'écouter plusieurs ports ou de multiples adresses. Afin de tester chaque socket pour voir s'il a une connexion en attente, Apache utilise select(2). select(2) indique si un socket a zéro ou au moins une connexion en attente. Le modèle d'Apache comporte plusieurs processus enfants, et tous ceux qui sont inactifs testent la présence de nouvelles connexions au même moment. Une implémentation rudimentaire de ceci pourrait ressembler à l'exemple suivant (ces exemples ne sont pas extraits du code d'Apache, ils ne sont proposés qu'à des fins pédagogiques) :

        for (;;) {
          for (;;) {
            fd_set accept_fds;

            FD_ZERO (&accept_fds);
            for (i = first_socket; i <= last_socket; ++i) {
              FD_SET (i, &accept_fds);
            }
            rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
            if (rc < 1) continue;
            new_connection = -1;
            for (i = first_socket; i <= last_socket; ++i) {
              if (FD_ISSET (i, &accept_fds)) {
                new_connection = accept (i, NULL, NULL);
                if (new_connection != -1) break;
              }
            }
            if (new_connection != -1) break;
          }
          process_the(new_connection);
        }

Mais cette implémentation rudimentaire présente une sérieuse lacune. Rappelez-vous que les processus enfants exécutent cette boucle au même moment ; ils vont ainsi bloquer sur select s'ils se trouvent entre deux requêtes. Tous ces processus bloqués vont se réactiver et sortir de select quand une requête va apparaître sur un des sockets (le nombre de processus enfants qui se réactivent varie en fonction du système d'exploitation et des réglages de synchronisation). Ils vont alors tous entrer dans la boucle et tenter un "accept" de la connexion. Mais seulement un d'entre eux y parviendra (en supposant qu'il ne reste q'une seule connexion en attente), les autres vont se bloquer au niveau de accept. Ceci verrouille vraiment ces processus de telle sorte qu'ils ne peuvent plus servir de requêtes que par cet unique socket, et il en sera ainsi jusqu'à ce que suffisamment de nouvelles requêtes apparaissent sur ce socket pour les réactiver tous. Cette lacune a été documentée pour la première fois dans PR#467. Il existe au moins deux solutions.

La première consiste à rendre les sockets non blocants. Dans ce cas, accept ne bloquera pas les processus enfants, et ils pourront continuer à s'exécuter immédiatement. Mais ceci consomme des ressources processeur. Supposons que vous ayez dix processus enfants inactifs dans select, et qu'une connexion arrive. Neuf des dix processus vont se réactiver, tenter un accept de la connexion, échouer, et boucler dans select, tout en n'ayant finalement rien accompli. Pendant ce temps, aucun de ces processus ne traite les requêtes qui arrivent sur d'autres sockets jusqu'à ce qu'ils retournent dans select. Finalement, cette solution ne semble pas très efficace, à moins que vous ne disposiez d'autant de processeurs inactifs (dans un serveur multiprocesseur) que de processus enfants inactifs, ce qui n'est pas une situation très courante.

Une autre solution, celle qu'utilise Apache, consiste à sérialiser les entrées dans la boucle interne. La boucle ressemble à ceci (les différences sont mises en surbrillance) :

        for (;;) {
          accept_mutex_on ();
          for (;;) {
            fd_set accept_fds;

            FD_ZERO (&accept_fds);
            for (i = first_socket; i <= last_socket; ++i) {
              FD_SET (i, &accept_fds);
            }
            rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
            if (rc < 1) continue;
            new_connection = -1;
            for (i = first_socket; i <= last_socket; ++i) {
              if (FD_ISSET (i, &accept_fds)) {
                new_connection = accept (i, NULL, NULL);
                if (new_connection != -1) break;
              }
            }
            if (new_connection != -1) break;
          }
          accept_mutex_off ();
          process the new_connection;
        }

Les fonctions accept_mutex_on et accept_mutex_off implémentent un sémaphore permettant une exclusion mutuelle. Un seul processus enfant à la fois peut posséder le mutex. Plusieurs choix se présentent pour implémenter ces mutex. Ce choix est défini dans src/conf.h (versions antérieures à 1.3) ou src/include/ap_config.h (versions 1.3 ou supérieures). Certaines architectures ne font pas ce choix du mode de verrouillage ; l'utilisation de directives Listen multiples sur ces architectures est donc peu sûr.

La directive Mutex permet de modifier l'implémentation du mutex mpm-accept à l'exécution. Des considérations spécifiques aux différentes implémentations de mutex sont documentées avec cette directive.

Une autre solution qui a été imaginée mais jamais implémentée, consiste à sérialiser partiellement la boucle -- c'est à dire y faire entrer un certain nombre de processus. Ceci ne présenterait un intérêt que sur les machines multiprocesseurs où plusieurs processus enfants peuvent s'exécuter simultanément, et encore, la sérialisation ne tire pas vraiment parti de toute la bande passante. C'est une possibilité d'investigation future, mais demeure de priorité basse car les serveurs web à architecture hautement parallèle ne sont pas la norme.

Pour bien faire, vous devriez faire fonctionner votre serveur sans directives Listen multiples si vous visez les performances les plus élevées. Mais lisez ce qui suit.

accept Serialization - point de connexion à un programme (sockets) unique

Ce qui précède convient pour les serveurs à sockets multiples, mais qu'en est-il des serveurs à socket unique ? En théorie, ils ne devraient pas rencontrer les mêmes problèmes car tous les processus enfants peuvent se bloquer dans accept(2) jusqu'à ce qu'une connexion arrive, et ils ne sont pas utilisés à ne rien faire. En pratique, ceci dissimule un même comportement de bouclage discuté plus haut dans la solution non-blocante. De la manière dont sont implémentées les piles TCP, le noyau réactive véritablement tous les processus bloqués dans accept quand une seule connexion arrive. Un de ces processus prend la connexion en compte et retourne dans l'espace utilisateur, les autres bouclant dans l'espace du noyau et se désactivant quand ils s'aperçoivent qu'il n'y a pas de connexion pour eux. Ce bouclage est invisible depuis le code de l'espace utilisateur, mais il est quand-même présent. Ceci peut conduire à la même augmentation de charge à perte que la solution non blocante au cas des sockets multiples peut induire.

Pour cette raison, il apparaît que de nombreuses architectures se comportent plus "proprement" si on sérialise même dans le cas d'une socket unique. Il s'agit en fait du comportement par défaut dans la plupart des cas. Des expériences poussées sous Linux (noyau 2.0.30 sur un biprocesseur Pentium pro 166 avec 128 Mo de RAM) ont montré que la sérialisation d'une socket unique provoque une diminution inférieure à 3% du nombre de requêtes par secondes par rapport au traitement non sérialisé. Mais le traitement non sérialisé des sockets uniques induit un temps de réponse supplémentaire de 100 ms pour chaque requête. Ce temps de réponse est probablement provoqué par une limitation sur les lignes à haute charge, et ne constitue un problème que sur les réseaux locaux. Si vous voulez vous passer de la sérialisation des sockets uniques, vous pouvez définir SINGLE_LISTEN_UNSERIALIZED_ACCEPT et les serveurs à socket unique ne pratiqueront plus du tout la sérialisation.

Fermeture en prenant son temps (Lingering close)

Comme discuté dans draft-ietf-http-connection-00.txt section 8, pour implémenter de manière fiable le protocole, un serveur HTTP doit fermer les deux directions d'une communication indépendamment (rappelez-vous qu'une connexion TCP est bidirectionnelle, chaque direction étant indépendante de l'autre).

Quand cette fonctionnalité fut ajoutée à Apache, elle causa une avalanche de problèmes sur plusieurs versions d'Unix à cause d'une implémentation à courte vue. La spécification TCP ne précise pas que l'état FIN_WAIT_2 possède un temps de réponse mais elle ne l'exclut pas. Sur les systèmes qui n'introduisent pas ce temps de réponse, Apache 1.2 induit de nombreux blocages définitifs de socket dans l'état FIN_WAIT_2. On peut eviter ceci dans de nombreux cas tout simplement en mettant à jour TCP/IP avec le dernier patch mis à disposition par le fournisseur. Dans les cas où le fournisseur n'a jamais fourni de patch (par exemple, SunOS4 -- bien que les utilisateurs possédant une license source puissent le patcher eux-mêmes), nous avons décidé de désactiver cette fonctionnalité.

Il y a deux méthodes pour arriver à ce résultat. La première est l'option de socket SO_LINGER. Mais le sort a voulu que cette solution ne soit jamais implémentée correctement dans la plupart des piles TCP/IP. Et même dans les rares cas où cette solution a été implémentée correctement (par exemple Linux 2.0.31), elle se montre beaucoup plus gourmande (en temps processeur) que la solution suivante.

Pour la plus grande partie, Apache implémente cette solution à l'aide d'une fonction appelée lingering_close (définie dans http_main.c). La fonction ressemble approximativement à ceci :

        void lingering_close (int s)
        {
          char junk_buffer[2048];

          /* shutdown the sending side */
          shutdown (s, 1);

          signal (SIGALRM, lingering_death);
          alarm (30);

          for (;;) {
            select (s for reading, 2 second timeout);
            if (error) break;
            if (s is ready for reading) {
              if (read (s, junk_buffer, sizeof (junk_buffer)) <= 0) {
                break;
              }
              /* just toss away whatever is here */
            }
          }

          close (s);
        }

Ceci ajoute naturellement un peu de charge à la fin d'une connexion, mais s'avère nécessaire pour une implémentation fiable. Comme HTTP/1.1 est de plus en plus présent et que toutes les connexions sont persistentes, la charge sera amortie par la multiplicité des requêtes. Si vous voulez jouer avec le feu en désactivant cette fonctionnalité, vous pouvez définir NO_LINGCLOSE, mais c'est fortement déconseillé. En particulier, comme les connexions persistantes en pipeline de HTTP/1.1 commencent à être utilisées, lingering_close devient une absolue nécessité (et les connexions en pipeline sont plus rapides ; vous avez donc tout intérêt à les supporter).

Fichier tableau de bord (Scoreboard file)

Les processus parent et enfants d'Apache communiquent entre eux à l'aide d'un objet appelé "Tableau de bord" (Scoreboard). Idéalement, cet échange devrait s'effectuer en mémoire partagée. Pour les systèmes d'exploitation auxquels nous avons eu accès, ou pour lesquels nous avons obtenu des informations suffisamment détaillées pour effectuer un portage, cet échange est en général implémenté en utilisant la mémoire partagée. Pour les autres, on utilise par défaut un fichier d'échange sur disque. Le fichier d'échange sur disque est non seulement lent, mais aussi peu fiable (et propose moins de fonctionnalités). Recherchez dans le fichier src/main/conf.h correspondant à votre architecture soit USE_MMAP_SCOREBOARD, soit USE_SHMGET_SCOREBOARD. La définition de l'un des deux (ainsi que leurs compagnons respectifs HAVE_MMAP et HAVE_SHMGET), active le code fourni pour la mémoire partagée. Si votre système propose une autre solution pour la gestion de la mémoire partagée, éditez le fichier src/main/http_main.c et ajoutez la portion de code nécessaire pour pouvoir l'utiliser dans Apache (Merci de nous envoyer aussi le patch correspondant).

Note à caractère historique : le portage d'Apache sous Linux n'utilisait pas la mémoire partagée avant la version 1.2. Ceci entraînait un comportement très rudimentaire et peu fiable des versions antérieures d'Apache sous Linux.

DYNAMIC_MODULE_LIMIT

Si vous n'avez pas l'intention d'utiliser les modules chargés dynamiquement (ce qui est probablement le cas si vous êtes en train de lire ce document afin de personnaliser votre serveur en recherchant le moindre des gains en performances), vous pouvez ajouter la définition -DDYNAMIC_MODULE_LIMIT=0 à la construction de votre serveur. Ceci aura pour effet de libérer la mémoire RAM allouée pour le chargement dynamique des modules.

Appendice : Analyse détaillée d'une trace

Voici la trace d'un appel système d'Apache 2.0.38 avec le MPM worker sous Solaris 8. Cette trace a été collectée à l'aide de la commande :

truss -l -p httpd_child_pid.

L'option -l demande à truss de tracer l'ID du LWP (lightweight process--la version de Solaris des threads niveau noyau) qui invoque chaque appel système.

Les autres systèmes peuvent proposer des utilitaires de traçage des appels système différents comme strace, ktrace, ou par. Ils produisent cependant tous une trace similaire.

Dans cette trace, un client a demandé un fichier statique de 10 ko au démon httpd. Le traçage des requêtes pour des contenus non statiques ou comportant une négociation de contenu a une présentation différente (et même assez laide dans certains cas).

/67:    accept(3, 0x00200BEC, 0x00200C0C, 1) (sleeping...)
/67:    accept(3, 0x00200BEC, 0x00200C0C, 1)            = 9

Dans cette trace, le thread à l'écoute s'exécute à l'intérieur de LWP #67.

Notez l'absence de la sérialisation d'accept(2). Sur cette plateforme spécifique, le MPM worker utilise un accept non sérialisé par défaut sauf s'il est en écoute sur des ports multiples.
/65:    lwp_park(0x00000000, 0)                         = 0
/67:    lwp_unpark(65, 1)                               = 0

Après avoir accepté la connexion, le thread à l'écoute réactive un thread du worker pour effectuer le traitement de la requête. Dans cette trace, le thread du worker qui traite la requête est associé à LWP #65.

/65:    getsockname(9, 0x00200BA4, 0x00200BC4, 1)       = 0

Afin de pouvoir implémenter les hôtes virtuels, Apache doit connaître l'adresse du socket local utilisé pour accepter la connexion. On pourrait supprimer cet appel dans de nombreuses situations (par exemple dans le cas où il n'y a pas d'hôte virtuel ou dans le cas où les directives Listen contiennent des adresses sans caractères de substitution). Mais aucun effort n'a été accompli à ce jour pour effectuer ces optimisations.

/65:    brk(0x002170E8)                                 = 0
/65:    brk(0x002190E8)                                 = 0

L'appel brk(2) alloue de la mémoire dans le tas. Ceci est rarement visible dans une trace d'appel système, car le démon httpd utilise des allocateurs mémoire de son cru (apr_pool et apr_bucket_alloc) pour la plupart des traitements de requêtes. Dans cette trace, le démon httpd vient juste de démarrer, et il doit appeler malloc(3) pour réserver les blocs de mémoire nécessaires à la création de ses propres allocateurs de mémoire.

/65:    fcntl(9, F_GETFL, 0x00000000)                   = 2
/65:    fstat64(9, 0xFAF7B818)                          = 0
/65:    getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B910, 2190656) = 0
/65:    fstat64(9, 0xFAF7B818)                          = 0
/65:    getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B914, 2190656) = 0
/65:    setsockopt(9, 65535, 8192, 0xFAF7B918, 4, 2190656) = 0
/65:    fcntl(9, F_SETFL, 0x00000082)                   = 0

Ensuite, le thread de worker passe la connexion du client (descripteur de fichier 9) en mode non blocant. Les appels setsockopt(2) et getsockopt(2) constituent un effet de bord de la manière dont la libc de Solaris utilise fcntl(2) pour les sockets.

/65:    read(9, " G E T   / 1 0 k . h t m".., 8000)     = 97

Le thread de worker lit la requête du client.

/65:    stat("/var/httpd/apache/httpd-8999/htdocs/10k.html", 0xFAF7B978) = 0
/65:    open("/var/httpd/apache/httpd-8999/htdocs/10k.html", O_RDONLY) = 10

Ce démon httpd a été configuré avec les options Options FollowSymLinks et AllowOverride None. Il n'a donc ni besoin d'appeler lstat(2) pour chaque répertoire du chemin du fichier demandé, ni besoin de vérifier la présence de fichiers .htaccess. Il appelle simplement stat(2) pour vérifier d'une part que le fichier existe, et d'autre part que c'est un fichier régulier, et non un répertoire.

/65:    sendfilev(0, 9, 0x00200F90, 2, 0xFAF7B53C)      = 10269

Dans cet exemple, le démon httpd peut envoyer l'en-tête de la réponse HTTP et le fichier demandé à l'aide d'un seul appel système sendfilev(2). La sémantique de sendfile varie en fonction des systèmes d'exploitation. Sur certains autres systèmes, il faut faire un appel à write(2) ou writev(2) pour envoyer les en-têtes avant d'appeler sendfile(2).

/65:    write(4, " 1 2 7 . 0 . 0 . 1   -  ".., 78)      = 78

Cet appel à write(2) enregistre la requête dans le journal des accès. Notez qu'une des choses manquant à cette trace est un appel à time(2). A la différence d'Apache 1.3, Apache 2.x utilise gettimeofday(3) pour consulter l'heure. Sur certains systèmes d'exploitation, comme Linux ou Solaris, gettimeofday est implémenté de manière optimisée de telle sorte qu'il consomme moins de ressources qu'un appel système habituel.

/65:    shutdown(9, 1, 1)                               = 0
/65:    poll(0xFAF7B980, 1, 2000)                       = 1
/65:    read(9, 0xFAF7BC20, 512)                        = 0
/65:    close(9)                                        = 0

Le thread de worker effectue une fermeture "en prenant son temps" (lingering close) de la connexion.

/65:    close(10)                                       = 0
/65:    lwp_park(0x00000000, 0)         (sleeping...)

Enfin, le thread de worker ferme le fichier qu'il vient de délivrer et se bloque jusqu'à ce que le thread en écoute lui assigne une autre connexion.

/67:    accept(3, 0x001FEB74, 0x001FEB94, 1) (sleeping...)

Pendant ce temps, le thread à l'écoute peut accepter une autre connexion à partir du moment où il a assigné la connexion présente à un thread de worker (selon une certaine logique de contrôle de flux dans le MPM worker qui impose des limites au thread à l'écoute si tous les threads de worker sont occupés). Bien que cela n'apparaisse pas dans cette trace, l'accept(2) suivant peut (et le fait en général, en situation de charge élevée) s'exécuter en parallèle avec le traitement de la connexion qui vient d'être acceptée par le thread de worker.


Conseils sur la sécurité - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Documentations diverses

Conseils sur la sécurité

Ce document propose quelques conseils et astuces concernant les problèmes de sécurité liés à l'installation d'un serveur web. Certaines suggestions seront à caractère général, tandis que d'autres seront spécifiques à Apache.

Maintenez votre serveur à jour

Le serveur HTTP Apache a une bonne réputation en matière de sécurité et possède une communauté de développeurs très sensibilisés aux problèmes de sécurité. Mais il est inévitable de trouver certains problèmes -- petits ou grands -- une fois le logiciel mis à disposition. C'est pour cette raison qu'il est crucial de se tenir informé des mises à jour. Si vous avez obtenu votre version du serveur HTTP directement depuis Apache, nous vous conseillons grandement de vous abonner à la Liste de diffusion des annonces du serveur HTTP qui vous informera de la parution des nouvelles versions et des mises à jour de sécurité. La plupart des distributeurs tiers d'Apache fournissent des services similaires.

Gardez cependant à l'esprit que lorsqu'un serveur web est compromis, le code du serveur HTTP n'est la plupart du temps pas en cause. Les problèmes proviennent plutôt de code ajouté, de scripts CGI, ou du système d'exploitation sous-jacent. Vous devez donc vous tenir informé des problèmes et mises à jour concernant tous les logiciels présents sur votre système.

Attaques de type "Déni de service" (Denial of Service - DoS)

Tous les services réseau peuvent faire l'objet d'attaques de type "Déni de service" qui tentent de les empêcher de répondre aux clients en saturant leurs ressources. Il est impossible de se prémunir totalement contre ce type d'attaques, mais vous pouvez accomplir certaines actions afin de minimiser les problèmes qu'elles créent.

Souvent, l'outil anti-DoS le plus efficace sera constitué par le pare-feu ou certaines configurations du système d'exploitation. Par exemple, la plupart des pare-feu peuvent être configurés de façon à limiter le nombre de connexions simultanées depuis une adresse IP ou un réseau, ce qui permet de prévenir toute une gamme d'attaques simples. Bien sûr, ceci n'est d'aucun secours contre les attaques de type "Déni de service" distribuées (DDoS).

Certains réglages de la configuration d'Apache peuvent aussi minimiser les problèmes :

  • La directive RequestReadTimeout permet de limiter le temps que met le client pour envoyer sa requête.
  • La valeur de la directive TimeOut doit être diminuée sur les sites sujets aux attaques DoS. Une valeur de quelques secondes devrait convenir. Cependant, comme TimeOut est actuellement concerné par de nombreuses opérations différentes, lui attribuer une valeur trop faible peut provoquer des problèmes avec les scripts CGI qui présentent un long temps de réponse.
  • La valeur de la directive KeepAliveTimeout doit aussi être diminuée sur les sites sujets aux attaques DoS. Certains sites désactivent même complètement le "maintien en vie" (keepalives) à l'aide de la directive KeepAlive, ce qui bien sûr présente des inconvénients en matière de performances.
  • Les valeurs des différentes directives fournies par d'autres modules et en rapport avec des délais doivent aussi être vérifiées.
  • Les directives LimitRequestBody, LimitRequestFields, LimitRequestFieldSize, LimitRequestLine, et LimitXMLRequestBody doivent être configurées avec prudence afin de limiter la consommation de ressources induite par les demandes des clients.
  • Sur les systèmes d'exploitation qui le supportent, assurez-vous que la directive AcceptFilter est activée afin de déléguer une partie du traitement des requêtes au système d'exploitation. Elle est activée par défaut dans le démon httpd d'Apache, mais peut nécessiter une reconfiguration de votre noyau.
  • Optimisez la directive MaxRequestWorkers de façon à définir le nombre maximum de connexions simultanées au dessus duquel les ressources s'épuisent. Voir aussi la documentation sur l'optimisation des performances.
  • L'utilisation d'un module mpm threadé vous permet de traiter d'avantage de connexions simultanées, ce qui minimise l'effet des attaques DoS. Dans le futur, le module mpm event utilisera un traitement asynchrone afin de ne pas dédier un thread à chaque connexion. De par la nature de la bibliothèque OpenSSL, le module mpm event est actuellement incompatible avec le module mod_ssl ainsi que d'autres filtres en entrée. Dans ces cas, son comportement se ramène à celui du module mpm worker.
  • Il existe de nombreux modules tiers disponibles à http://modules.apache.org/ qui peuvent retreindre les comportements de certains clients et ainsi minimiser les problèmes de DoS.

Permissions sur les répertoires de la racine du serveur

Typiquement, Apache est démarré par l'utilisateur root, puis il devient la propriété de l'utilisateur défini par la directive User afin de répondre aux demandes. Comme pour toutes les commandes exécutées par root, vous devez vous assurer qu'elle n'est pas modifiable par les utilisateurs autres que root. Les fichiers eux-mêmes, mais aussi les répertoires ainsi que leurs parents ne doivent être modifiables que par root. Par exemple, si vous avez choisi de placer la racine du serveur dans /usr/local/apache, il est conseillé de créer le répertoire en tant que root, avec des commandes du style :

mkdir /usr/local/apache
cd /usr/local/apache
mkdir bin conf logs
chown 0 . bin conf logs
chgrp 0 . bin conf logs
chmod 755 . bin conf logs

Nous supposerons que /, /usr et /usr/local ne sont modifiables que par root. Quand vous installez l'exécutable httpd, vous devez vous assurer qu'il possède des protections similaires :

cp httpd /usr/local/apache/bin
chown 0 /usr/local/apache/bin/httpd
chgrp 0 /usr/local/apache/bin/httpd
chmod 511 /usr/local/apache/bin/httpd

Vous pouvez créer un sous-répertoire htdocs modifiable par d'autres utilisateurs -- car root ne crée ni exécute aucun fichier dans ce sous-répertoire.

Si vous permettez à des utilisateurs non root de modifier des fichiers que root écrit ou exécute, vous exposez votre système à une compromission de l'utilisateur root. Par exemple, quelqu'un pourrait remplacer le binaire httpd de façon à ce que la prochaine fois que vous le redémarrerez, il exécutera un code arbitraire. Si le répertoire des journaux a les droits en écriture (pour un utilisateur non root), quelqu'un pourrait remplacer un fichier journal par un lien symbolique vers un autre fichier système, et root pourrait alors écraser ce fichier avec des données arbitraires. Si les fichiers journaux eux-mêmes ont des droits en écriture (pour un utilisateur non root), quelqu'un pourrait modifier les journaux eux-mêmes avec des données fausses.

Inclusions côté serveur

Les inclusions côté serveur (Server Side Includes - SSI) exposent l'administrateur du serveur à de nombreux risques potentiels en matière de sécurité.

Le premier risque est l'augmentation de la charge du serveur. Tous les fichiers où SSI est activé doivent être analysés par Apache, qu'ils contiennent des directives SSI ou non. L'augmentation de la charge induite est minime, mais peut devenir significative dans le contexte d'un serveur partagé.

Les fichiers SSI présentent les mêmes risques que les scripts CGI en général. Les fichiers où SSI est activé peuvent exécuter tout script CGI ou autre programme à l'aide de la commande "exec cmd" avec les permissions des utilisateur et groupe sous lesquels Apache s'exécute, comme défini dans httpd.conf.

Des méthodes existent pour améliorer la sécurité des fichiers SSI, tout en tirant parti des bénéfices qu'ils apportent.

Pour limiter les dommages qu'un fichier SSI agressif pourrait causer, l'administrateur du serveur peut activersuexec comme décrit dans la section Les CGI en général.

L'activation des SSI pour des fichiers possédant des extensions .html ou .htm peut s'avérer dangereux. Ceci est particulièrement vrai dans un environnement de serveur partagé ou étant le siège d'un traffic élevé. Les fichiers où SSI est activé doivent posséder une extension spécifique, telle que la conventionnelle .shtml. Ceci permet de limiter la charge du serveur à un niveau minimum et de simplifier la gestion des risques.

Une autre solution consiste à interdire l'exécution de scripts et programmes à partir de pages SSI. Pour ce faire, remplacez Includes par IncludesNOEXEC dans la directive Options. Notez que les utilisateurs pourront encore utiliser <--#include virtual="..." --> pour exécuter des scripts CGI si ces scripts sont situés dans des répertoires spécifiés par une directive ScriptAlias.

Les CGI en général

Tout d'abord, vous devez toujours garder à l'esprit que vous devez faire confiance aux développeurs de scripts ou programmes CGI ainsi qu'à vos compétences pour déceler les trous de sécurité potentiels dans les CGI, que ceux-ci soient délibérés ou accidentels. Les scripts CGI peuvent essentiellement exécuter des commandes arbitraires sur votre système avec les droits de l'utilisateur du serveur web, et peuvent par conséquent être extrèmement dangereux s'ils ne sont pas vérifiés avec soin.

Tous les scripts CGI s'exécutent sous le même utilisateur, il peuvent donc entrer en conflit (accidentellement ou délibérément) avec d'autres scripts. Par exemple, l'utilisateur A hait l'utilisateur B, il écrit donc un script qui efface la base de données CGI de l'utilisateur B. Vous pouvez utiliser le programme suEXEC pour faire en sorte que les scripts s'exécutent sous des utilisateurs différents. Ce programme est inclus dans la distribution d'Apache depuis la version 1.2 et est appelé à partir de certaines portions de code du serveur Apache. Une autre méthode plus connue est l'utilisation de CGIWrap.

CGI sans alias de script

Vous ne devez permettre aux utilisateurs d'exécuter des scripts CGI depuis n'importe quel répertoire que dans l'éventualité où :

  • Vous faites confiance à vos utilisateurs pour ne pas écrire de scripts qui vont délibérément ou accidentellement exposer votre système à une attaque.
  • Vous estimez que le niveau de sécurité dans les autres parties de votre site est si faible qu'un trou de sécurité de plus ou de moins n'est pas très important.
  • Votre système ne comporte aucun utilisateur, et personne ne visite jamais votre site.

CGI avec alias de script

Le confinement des CGI dans des répertoires spécifiques permet à l'administrateur de contrôler ce que l'on met dans ces répertoires. Ceci est bien entendu mieux sécurisé que les CGI sans alias de script, mais seulement à condition que les utilisateurs avec les droits en écriture sur les répertoires soient dignes de confiance, et que l'administrateur ait la volonté de tester chaque programme ou script CGI à la recherche d'éventuels trous de sécurité.

La plupart des sites choisissent cette approche au détriment des CGI sans alias de script.

Autres sources de contenu dynamique

Les options de scripting intégrées qui s'exécutent en tant que partie du serveur lui-même, comme mod_php, mod_perl, mod_tcl, et mod_python, s'exécutent sous le même utilisateur que le serveur (voir la directive User), et par conséquent, les scripts que ces moteurs exécutent peuvent accéder aux mêmes ressources que le serveur. Certains moteurs de scripting peuvent proposer des restrictions, mais pour plus de sûreté, il vaut mieux partir du principe que ce n'est pas le cas.

Protection de la configuration du système

Pour contrôler étroitement votre serveur, vous pouvez interdire l'utilisation des fichiers .htaccess qui permettent de passer outre les fonctionnalités de sécurité que vous avez configurées. Voici un moyen pour y parvenir :

Ajoutez dans le fichier de configuration du serveur

<Directory "/">
    AllowOverride None
</Directory>

Ceci interdit l'utilisation des fichiers .htaccess dans tous les répertoires, sauf ceux pour lesquels c'est explicitement autorisé.

Notez que c'est la configuration par défaut depuis Apache 2.3.9.

Protection par défaut des fichiers du serveur

Le concept d'accès par défaut est un aspect d'Apache qui est parfois mal compris. C'est à dire que, à moins que vous ne changiez explicitement ce comportement, si le serveur trouve son chemin vers un fichier en suivant les règles normales de correspondance URL - fichier, il peut le retourner aux clients.

Considérons l'exemple suivant :

# cd /; ln -s / public_html
puis accès à http://localhost/~root/

Ceci permettrait aux clients de parcourir l'ensemble du système de fichiers. Pour l'éviter, ajoutez le bloc suivant à la configuration de votre serveur :

<Directory "/">
    Require all denied
</Directory>

ceci va interdire l'accès par défaut à tous les fichiers du système de fichiers. Vous devrez ensuite ajouter les blocs Directory appropriés correspondant aux répertoires auxquels vous voulez autorisez l'accès. Par exemple,

<Directory "/usr/users/*/public_html">
    Require all granted
</Directory>
<Directory "/usr/local/httpd">
    Require all granted
</Directory>

Portez une attention particulière aux interactions entre les directives Location et Directory ; par exemple, si une directive <Directory ""/> interdit un accès, une directive <Location "/"> pourra passer outre.

De même, soyez méfiant en jouant avec la directive UserDir ; la positionner à "./" aurait le même effet, pour root, que le premier exemple plus haut. Nous vous conseillons fortement d'inclure la ligne suivante dans le fichier de configuration de votre serveur :

UserDir disabled root

Surveillez vos journaux

Pour vous tenir informé de ce qui se passe réellement dans votre serveur, vous devez consulter vos fichiers journaux. Même si les fichiers journaux ne consignent que des évènements qui se sont déjà produits, ils vous informeront sur la nature des attaques qui sont lancées contre le serveur et vous permettront de vérifier si le niveau de sécurité nécessaire est atteint.

Quelques exemples :

grep -c "/jsp/source.jsp?/jsp/ /jsp/source.jsp??" access_log
grep "client denied" error_log | tail -n 10

Le premier exemple listera les attaques essayant d'exploiter la vulnérabilité d'Apache Tomcat pouvant provoquer la divulgation d'informations par des requêtes Source.JSP mal formées, le second donnera la liste des dix dernières interdictions client ; par exemple :

[Thu Jul 11 17:18:39 2002] [error] [client foo.example.com] client denied by server configuration: /usr/local/apache/htdocs/.htpasswd

Comme vous le voyez, les fichiers journaux ne consignent que ce qui s'est déjà produit ; ainsi, si le client a pu accéder au fichier .htpasswd, vous devriez avoir quelque chose du style :

foo.example.com - - [12/Jul/2002:01:59:13 +0200] "GET /.htpasswd HTTP/1.1"

dans votre journal des accès ; ce qui signifie que vous avez probablement mis en commentaire ce qui suit dans le fichier de configuration de votre serveur :

<Files ".ht*">
    Require all denied
</Files>

Fusion des sections de configuration

La fusion des sections de configuration est complexe et dépend souvent des directives utilisées. Vous devez systématiquement tester vos modifications pour vérifier la manière dont les directives sont fusionnées.

Concernant les modules qui n'implémentent aucune logique de fusion, comme mod_access_compat, le comportement des sections suivantes est tributaire de la présence dans ces dernières de directives appartenant à ces modules. La configuration est héritée jusqu'à ce qu'une modification soit effectuée ; à ce moment, la configuration est remplacée et non fusionnée.


Standards applicables - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Documentations diverses

Standards applicables

Cette page documente tous les standards applicables que suit le serveur HTTP Apache, accompagnés d'une brève description.

Pour compléter les informations fournies ci-dessous, vous pouvez consulter les ressources suivantes :

  • http://purl.org/NET/http-errata - Corrections de la spécification HTTP/1.1
  • http://www.rfc-editor.org/errata.php - Corrections des RFCs
  • http://ftp.ics.uci.edu/pub/ietf/http/#RFC - Une liste précompilée des RFCs en rapport avec HTTP

Avertissement

Ce document n'est pas encore finalisé.

Recommandations HTTP

Indépendamment des modules compilés et utilisés, Apache en tant que serveur web de base respecte les recommandations IETF suivantes :

RFC 1945 (Informations)
Le Protocole de Transfert Hypertexte (Hypertext Transfer Protocol - HTTP) est un protocole de niveau application avec la clarté et la vitesse nécessaires pour les systèmes d'informations distribués, collaboratifs et hypermédia. Cette RFC documente le protocole HTTP/1.0.
RFC 2616 (Série de standards)
Le Protocole de Transfert Hypertexte (Hypertext Transfer Protocol - HTTP) est un protocole de niveau application pour les systèmes d'informations distribués, collaboratifs et hypermédia. Cette RFC documente le protocole HTTP/1.1.
RFC 2396 (Série de standards)
Un Identificateur de Ressource Uniforme (Uniform Resource Identifier - URI) est une chaîne de caractères compacte permettant d'identifier une ressource physique ou abstraite.
RFC 4346 (Série de standards)
Le protocole TLS permet l'utilisation de communications sécurisées sur l'Internet. Il fournit le chiffrement, et a été conçu pour se prémunir contre l'interception, la modification et la falsification de messages.

Recommandations HTML

En ce qui concerne le langage HTML, Apache respecte les recommandations IETF et W3C suivantes :

RFC 2854 (Informations)
Ce document résume l'historique du développement de HTML, et définit le type MIME "text/html" en pointant les recommandations W3C correspondantes.
Spécification HTML 4.01 (Corrections d'erreurs)
Cette spécification définit le Langage à Balises HyperTexte (HyperText Markup Language - HTML), le langage de publication du World Wide Web. Elle définit HTML 4.01, qui est une sous-version de HTML 4.
Référence HTML 3.2
Le langage à Balises HyperTexte (HyperText Markup Language - HTML) est un langage à balises simple permettant de créer des documents hypertextes portables. Les documents HTML sont aussi des documents SGML.
XHTML 1.1 - XHTML sous forme de modules (Corrections d'erreurs)
Cette recommandation définit un nouveau type de document XHTML basé sur le cadre de développement des modules et les modules définis dans la modularisation de XHTML.
XHTML 1.0, le Langage à Balises Hypertexte Extensible (Extensible HyperText Markup Language) - Seconde édition (Corrections d'erreurs)
Cette spécification définit la seconde édition de XHTML 1.0, une reformulation de HTML 4 en tant qu'application XML 1.0, ainsi que trois DTDs correspondant à celles définies par HTML 4.

Authentification

En ce qui concerne les différentes méthodes d'authentification, Apache respecte les recommandations IETF suivantes :

RFC 2617 (Le track des standards)
"HTTP/1.0", y compris la spécification d'un protocole basique d'authentification et de contrôle d'accès.

Codes de langues et de pays

Les liens suivants fournissent des informations à propos des codes de langues et de pays aux normes ISO ou autres :

ISO 639-2
ISO 639 fournit deux jeux de codes de langues permettant de représenter les noms des langues ; le premier est un jeu de codes sur deux lettres (639-1), le second (celui présenté dans le lien ci-dessus), est un jeu de codes sur trois lettres (639-2).
ISO 3166-1
Ce document présente les noms de pays (les noms raccourcis officiels en anglais) dans l'ordre alphabétique, tels qu'ils sont présentés dans la norme ISO 3166-1 et les éléments de codes correspondants de la norme ISO 3166-1-alpha-2.
BCP 47 (Les meilleurs pratiques courantes), RFC 3066
Ce document décrit une balise de langue permettant de spécifier la langue utilisé dans un objet contenant des informations, la manière d'enregistrer des valeurs à utiliser dans cette balise de langage, et une méthode pour comparer les balises de langue de ce style.
RFC 3282 (Série de standards)
Ce document définit un en-tête "Content-language:" permettant de spécifier le langage d'un élément possédant des en-têtes du style RFC 822, comme les portions de corps MIME ou les documents Web, et un en-tête "Accept-Language:" permettant de spécifier des préférences en matière de langue.


Formats de mots de passe - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Documentations diverses

Formats de mots de passe

Notes à propos des formats de chiffrement des mots de passe générés et compris par Apache.

Authentification de base

Voici les cinq formats de mots de passe qu'Apache reconnaît pour l'authentification de base. Notez que tous les formats ne sont pas supportés par toutes les plates-formes :

bcrypt
"$2y$" + the result of the crypt_blowfish algorithm. Dérivé de l'algorythme de chiffrement crypt_blowfish. Voir le fichier source APR crypt_blowfish.c pour plus de détails à propos de cet algorithme.
MD5
"$apr1$" + le résultat d'un algorithme spécifique à Apache utilisant un condensé MD5 réitéré (1000 fois) de combinaisons variées du mot de passe et d'une source d'entropie sur 32 bits. Voir le fichier source APR apr_md5.c pour les détails de l'algorithme.
SHA1
"{SHA}" + un condensé SHA-1 du mot de passe codé en Base64. Non sûr.
CRYPT
Unix seulement. Utilise la fonction Unix traditionnelle crypt(3) avec une source d'entropie sur 32 bits (seuls 12 bits sont utilisés), et seulement les 8 premiers caractères du mot de passe. Non sûr.
PLAIN TEXT (autrement dit non chiffré)
Windows & Netware seulement. Non sûr.

Générer des mots de passe avec htpasswd

bcrypt

$ htpasswd -nbB monNom monMot-de-passe
monNom:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC

MD5

$ htpasswd -nbm monNom monMot-de-passe
monNom:$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

SHA1

$ htpasswd -nbs monNom monMot-de-passe
monNom:{SHA}VBPuJHI7uixaa6LQGWx4s+5GKNE=

CRYPT

$ htpasswd -nbd monNom monMot-de-passe
monNom:rqXexS6ZhobKA

Générer des mots de passe CRYPT and MD5 avec le programme OpenSSL en ligne de commande

OpenSSL connaît l'algorithme MD5 spécifique à Apache.

MD5

$ openssl passwd -apr1 monMot-de-passe
$apr1$qHDFfhPC$nITSVHgYbDAK1Y0acGRnY0

CRYPT

openssl passwd -crypt monMot-de-passe
qQ5vTYO3c8dsU

Valider des mots de passe CRYPT and MD5 avec le programme OpenSSL en ligne de commande

La source d'entropie pour un mot de passe CRYPT est constituée des deux premiers caractères (convertis en valeur binaire). Pour valider monMot-de-passe par rapport à rqXexS6ZhobKA

CRYPT

$ openssl passwd -crypt -salt rq monMot-de-passe
Warning: truncating password to 8 characters
rqXexS6ZhobKA

Notez que spécifier monMot-d au lieu de monMot-de-passe produira le même résultat car seuls les 8 premiers caractères des mots de passe CRYPT sont pris en compte.

La source d'entropie pour un mot de passe MD5 se situe entre $apr1$ et le caractère $ suivant (sous la forme d'une valeur binaire codée en Base64 - au maximum 8 caractères). Pour valider monMot-de-passe par rapport à $apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

MD5

$ openssl passwd -apr1 -salt r31..... monMot-de-passe
$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

Champs mot de passe de base de données pour mod_dbd

La variante SHA1 constitue probablement le format le mieux approprié pour l'authentification DBD. Comme les fonctions SHA1 et Base64 sont en général disponibles, d'autres logiciels peuvent renseigner une base de données avec des mots de passe chiffrés utilisables par l'authentification basique d'Apache.

Pour créer des mots de passe au format SHA1 pour l'authentification de base d'Apache dans divers langages :

PHP

'{SHA}' . base64_encode(sha1($password, TRUE))

Java

"{SHA}" + new sun.misc.BASE64Encoder().encode(java.security.MessageDigest.getInstance("SHA1").digest(password.getBytes()))

ColdFusion

"{SHA}" & ToBase64(BinaryDecode(Hash(password, "SHA1"), "Hex"))

Ruby

require 'digest/sha1'
require 'base64'
'{SHA}' + Base64.encode64(Digest::SHA1.digest(password))

C ou C++

Utilisez la fonction APR : apr_sha1_base64

Python

import base64
import hashlib
"{SHA}" + format(base64.b64encode(hashlib.sha1(password).digest()))

PostgreSQL (avec les fonctions contrib/pgcrypto installées)

'{SHA}'||encode(digest(password,'sha1'),'base64')

Authentification à base de condensés

Apache ne reconnaît qu'un format pour les mots de passe d'authentification à base de condensés - le condensé MD5 de la chaîne utilisateur:domaine-de-protection:mot-de-passe sous la forme d'une chaîne de 32 caractères au format hexadécimal. domaine-de-protection est l'identifiant du domaine de protection de l'autorisation passé en argument à la directive AuthName dans httpd.conf.

Champs de mot de passe de base de données pour mod_dbd

Comme la fonction MD5 est en général disponible, d'autres logiciels peuvent renseigner une base de données avec des mots de passe chiffrés utilisables par l'authentification à base de condensés d'Apache.

Pour créer des mots de passe pour l'authentification à base de condensés d'Apache dans divers langages :

PHP

md5($user . ':' . $realm . ':' .$password)

Java

      byte b[] = java.security.MessageDigest.getInstance("MD5").digest( (user + ":" + realm + ":" + password ).getBytes());
java.math.BigInteger bi = new java.math.BigInteger(1, b);
String s = bi.toString(16);
while (s.length() < 32)
s = "0" + s;

      // La chaîne s contient le mot de passe chiffré

ColdFusion

LCase(Hash( (user & ":" & realm & ":" & password) , "MD5"))

Ruby

require 'digest/md5'
Digest::MD5.hexdigest(user + ':' + realm + ':' + password)

PostgreSQL (avec les fonctions contrib/pgcrypto installées)

encode(digest( user || ':' || realm || ':' || password , 'md5'), 'hex')


Termes utilisés pour décrire les modules - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Termes utilisés pour décrire les modules

Ce document décrit les termes utilisés pour décrire chaque module Apache.

Description

Une brève description des fonctions du module.

Statut

Ce terme indique le degré de rapprochement du module par rapport au coeur du serveur web Apache ; en d'autres termes, vous pouvez être amené à recompiler le serveur pour pouvoir accéder au module et à ses fonctionnalités. Les valeurs possibles de cet attribut sont :

MPM
Un module dont le statut est "MPM" est un module Multi-Processus. A la différence des autres modules, un seul module MPM peut et doit être utilisé par Apache à la fois. Ce type de module est responsable de la répartition et du traitement de base des requêtes.
Base
Un module dont le statut est "Base" est compilé dans le serveur et chargé avec ce dernier par défaut ; il est donc toujours disponible à moins que vous n'ayez fait en sorte de supprimer le module de votre configuration.
Extension
Un module dont le statut est "Extension" n'est pas compilé et chargé dans le serveur par défaut. Pour activer le module et accéder à ses fonctionnalités, vous devez modifier la configuration de la compilation du serveur et recompiler Apache.
Expérimental
Le statut "Experimental" indique que le module fait partie du kit Apache, mais que vous devez l'utiliser à vos risques et périls. Le module est documenté à des fins d'exhaustivité, et n'est pas obligatoirement supporté.
Externe
Ce statut indique que le module ("module tiers") ne fait pas partie de la distribution de base d'Apache. Nous ne sommes pas responsables de ces modules et n'en assurons pas le support.

Fichier source

Il s'agit tout simplement de la liste des noms des fichiers source qui contiennent le code du module. C'est aussi le nom utilisé par la directive <IfModule>.

Identificateur de module

C'est une chaîne permettant d'identifier le module à utiliser dans la directive LoadModule pour le chargement dynamique des modules. En particulier, c'est le nom de la variable externe de type module dans le fichier source.

Compatibilité

Si le module ne faisait pas partie de la distribution originale d'Apache version 2, la version à partir de laquelle il est disponible est indiquée ici. En outre, si le module n'est disponible que sur certaines plates-formes, cela sera mentionné ici.


Termes utilisés pour la description des directives - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Termes utilisés pour la description des directives

Ce document décrit les termes utilisés pour décrire chaque directive de configuration d'Apache.

Voir aussi

  • Fichiers de configuration

Description

Une brève description des fonctions de cette directive.

Syntaxe

Ce terme introduit le format sous lequel la directive doit apparaître dans le fichier de configuration. Cette syntaxe est très spécifique à la directive et est décrite en détail dans la définition de cette dernière. En général, le nom de la directive est suivi d'un ou plusieurs arguments séparés par des espaces. Si un argument contient un espace, il doit être entouré de guillemets. Les arguments optionnels sont entourés de crochets. Lorsqu'un argument accepte une valeur parmi une liste de valeurs possibles, cette liste est spécifiée en séparant les valeurs par une barre verticale "|". Les textes littéraux sont présentés dans la fonte par défaut, alors que les types d'argument pour lesquels une substitution est nécessaire sont en gras. La syntaxe des directives acceptant un nombre variable d'arguments se termine par "...", ce qui indique que le dernier argument peut être répété.

Les directives utilisent un grand nombre de types d'arguments différents. Les plus courants sont définis ci-dessous.

URL
Un Localisateur de Ressource Uniforme (Uniform Resource Locator) complet comportant un protocole, un nom d'hôte et un nom de chemin optionnel comme dans http://www.example.com/chemin/vers/fichier.html
chemin-URL
La partie de l'url qui suit le protocole et le nom d'hôte comme dans /chemin/vers/fichier.html. Le chemin-URL représente la ressource vue du web, et est différente de la représentation de cette même ressource vue du système de fichiers.
chemin-fichier
Le chemin d'un fichier dans le système de fichiers local commençant par le répertoire racine comme dans /usr/local/apache/htdocs/chemin/vers/fichier.html. Sauf mention contraire, un chemin-fichier qui ne commence pas par un slash sera considéré comme relatif au répertoire défini par la directive ServerRoot.
chemin-répertoire
Le chemin d'un répertoire dans le système de fichiers local commençant par le répertoire racine comme dans /usr/local/apache/htdocs/chemin/vers/.
nom-fichier
Le nom d'un fichier sans son chemin comme dans fichier.html.
regex
Une expression rationnelle compatible Perl. La définition de la directive spécifiera à quoi regex sera comparée.
extension
En général, c'est la partie du nom de fichier qui suit le dernier point. Cependant, Apache reconnaît plusieurs extensions de noms de fichiers ; ainsi, si un nom de fichier contient plusieurs points, chacune des parties du nom de fichier séparées par des points et situées après le premier point est une extension. Par exemple, le nom de fichier fichier.html.en comporte deux extensions : .html et .en. Pour les directives Apache, vous pouvez spécifier les extensions avec ou sans le point initial. Enfin, les extensions ne sont pas sensibles à la casse.
MIME-type
Une méthode de description du format d'un fichier consistant en un type de format majeur et un type de format mineur séparés par un slash comme dans text/html.
env-variable
Le nom d'une variable d'environnement définie au cours du processus de configuration d'Apache. Notez qu'elle peut être différente d'une variable d'environnement du système d'exploitation. Voir la documentation sur les variables d'environnement pour plus de détails.

Défaut

Si la directive possède une valeur par défaut (en d'autres termes, si le serveur Web Apache se comporte comme si vous l'aviez définie à une valeur particulière, alors que vous l'avez omise dans votre configuration), elle est spécifiée ici. Si la directive ne possède pas de valeur par défaut, cette section doit spécifier "Aucune". Notez que la valeur par défaut dont il est question n'est pas nécessairement la même que la valeur attribuée à la directive dans le fichier httpd.conf par défaut distribué avec le serveur.

Contexte

Indique les parties des fichiers de configuration du serveur où cette directive est valide. Il s'agit d'une liste d'une ou plusieurs des valeurs suivantes séparées par des virgules :

configuration du serveur
Signifie que la directive peut être utilisée dans les fichiers de configuration du serveur (par exemple httpd.conf), mais pas à l'intérieur d'un conteneur <VirtualHost> ou <Directory>. De même, elle n'est pas valide dans les fichiers .htaccess.
serveur virtuel
Signifie que la directive peut apparaître à l'intérieur d'un conteneur <VirtualHost> dans les fichiers de configuration du serveur.
répertoire
Une directive spécifiée comme valide dans ce contexte peut être utilisée à l'intérieur de conteneurs <Directory>, <Location>, <Files>, <If>, et <Proxy> dans les fichiers de configuration du serveur, en tenant compte des restrictions précisées dans la documentation sur les Sections de configuration.
.htaccess
Si une directive est valide dans ce contexte, cela signifie qu'elle peut apparaître à l'intérieur de fichiers de configuration de niveau répertoire .htaccess. Elle sera ou ne sera pas traitée, selon la définition de l'option overrides pour le contexte courant.

La directive n'est autorisée que dans le contexte désigné ; si vous essayez de l'utiliser ailleurs, vous générerez une erreur de configuration qui va soit empêcher le serveur de traiter les requêtes correctement dans ce contexte, soit tout simplement empêcher le serveur de fonctionner -- en d'autres termes, le serveur refusera de démarrer.

Les lieux de définition valides pour une directive résultent en fait d'un OU logique de tous les contextes spécifiés. En d'autres termes, une directive spécifiée comme valide dans "configuration du serveur, .htaccess" peut être utilisée dans le fichier httpd.conf et dans les fichiers .htaccess, mais pas dans un conteneur <Directory> ou <VirtualHost>.

Surcharge/Écrasement

Ce terme indique quelle autorisation de surcharge ("override") doit être active pour que la directive puisse être traitée lorsqu'elle apparaît dans un fichier .htaccess. Si le context de la directive ne lui permet pas d'apparaître dans un fichier .htaccess, aucun contexte ne sera spécifié.

Les autorisations de surcharge sont activées via la directive AllowOverride, et possèdent une portée particulière, comme un répertoire et tous ses sous-répertoires, sauf si une autre directive AllowOverride apparaît à un niveau inférieur. La documentation pour cette directive spécifie aussi les noms d'autorisations de surcharge disponibles.

Statut

Cet attribut indique le degré de rapprochement de la directive du coeur d'Apache ; en d'autres termes, vous pouvez être amené à recompiler le serveur avec un jeu de modules supplémentaires pour pouvoir utiliser la directive, et ainsi accéder à ses fonctionnalités. Les valeurs possible pour cet attribut sont :

Core
Lorsqu'une directive a pour statut "Core", cela signifie qu'elle fait partie du coeur du serveur web Apache, et est de ce fait toujours disponible.
MPM
Une directive dont le statut est "MPM" est fournie par un module Multi-Processus. Ce type de directive sera disponible si et seulement si vous utilisez un des MPMs spécifiés dans la ligne Module de la définition de la directive.
Base
Une directive dont le statut est "Base" est fournie par un des modules Apache standards qui sont compilés dans le serveur par défaut, et sont de ce fait toujours disponibles, sauf si vous avez fait en sorte de les supprimer de votre configuration.
Extension
Une directive dont le statut est "Extension" est fournie par un des modules inclus dans le kit du serveur Apache, mais qui ne sont pas compilés dans le serveur par défaut. Pour activer la directive et accéder à ses fonctionnalités, vous devez modifier les fichiers de configuration de la compilation du serveur, et recompiler Apache.
Expérimental
Le statut "Expérimental" indique que la directive fait partie du kit Apache, mais que vous l'utilisez à vos risques et périls. La directive est documentée à titre d'exhaustivité, et n'est pas obligatoirement supportée. Le module qui fournit la directive peut être compilé par défaut dans le serveur ou non ; consultez le haut de la page qui décrit la directive et son module pour vérifier sa disponibilité.

Module

Il s'agit d'une simple liste des noms des modules sources qui fournissent la directive.

Compatibilité

Si la directive ne faisait pas partie de la distribution originale d'Apache version 2, la version dans laquelle elle a été introduite est indiquée ici. Cette section indique aussi si la directive n'est disponible que sur certaines plates-formes.


core - Serveur Apache HTTP Version 2.4

Fonctionalités de Base Apache

Description: | Fonctionnalités de base du serveur HTTP Apache toujours disponibles
Statut: | Core

Directive AcceptFilter

Description: | Permet d'optimiser la configuration d'une socket pour l'écoute d'un protocole
Syntaxe: | AcceptFilter protocole filtre d'acceptation
Contexte: | configuration du serveur
Statut: | Core
Module: | core

Cette directive permet d'effectuer une optimisation de la socket d'écoute d'un type de protocole en fonction du système d'exploitation. Le but premier est de faire en sorte que le noyau n'envoie pas de socket au processus du serveur jusqu'à ce que des données soient reçues, ou qu'une requête HTTP complète soit mise en tampon. Seuls les Filtres d'acceptation de FreeBSD, le filtre plus primitif TCP_DEFER_ACCEPT sous Linux, et la version optimisée d'AcceptEx() de Windows sont actuellement supportés.

L'utilisation de l'argument none va désactiver tout filtre d'acceptation pour ce protocole. Ceci s'avère utile pour les protocoles qui nécessitent l'envoi de données par le serveur en premier, comme ftp: ou nntp:

AcceptFilter nntp none

Les noms de protocoles par défaut sont https pour le port 443 et http pour tous les autres ports. Pour spécifier un autre protocole à utiliser avec un port en écoute, ajoutez l'argument protocol à la directive Listen.

Sous FreeBSD, les valeurs par défaut sont :

AcceptFilter http httpready
AcceptFilter https dataready

Le filtre d'acceptation httpready met en tampon des requêtes HTTP entières au niveau du noyau. Quand une requête entière a été reçue, le noyau l'envoie au serveur. Voir la page de manuel de accf_http(9) pour plus de détails. Comme les requêtes HTTPS sont chiffrées, celles-ci n'autorisent que le filtre accf_data(9).

Sous Linux, les valeurs par défaut sont :

AcceptFilter http data
AcceptFilter https data

Le filtre TCP_DEFER_ACCEPT de Linux ne supporte pas la mise en tampon des requêtes http. Toute valeur autre que none active le filtre TCP_DEFER_ACCEPT pour ce protocole. Pour plus de détails, voir la page de manuel Linux de tcp(7).

Sous Windows, les valeurs par défaut sont :

AcceptFilter http connect
AcceptFilter https connect

Le module MPM pour Windows mpm_winnt utilise la directive AcceptFilter comme commutateur de l'API AcceptEx(), et ne supporte pas la mise en tampon du protocole http. connect utilise l'API AcceptEx(), extrait aussi les adresses réseau finales, mais à l'instar de none, la valeur connect n'attend pas la transmission des données initiales.

Sous Windows, none utilise accept() au lieu d'AcceptEx(), et ne recycle pas les sockets entre les connexions. Ceci s'avère utile pour les interfaces réseau dont le pilote est défectueux, ainsi que pour certains fournisseurs de réseau comme les pilotes vpn, ou les filtres anti-spam, anti-virus ou anti-spyware.

L'AcceptFilter data (Windows)

Jusqu'à la version 2.4.23, le filtre d'acceptation data attendait que des données aient été transmises et que le tampon de données initial et l'adresse réseau finale aient été déterminés par l'invocation AcceptEx(). Cette implémentation étant vulnérable à une attaque de type denial of service, elle a été désactivée.

La version actuelle de httpd prend par défaut le filtre connect sous Windows, et reprendra la valeur data si data est spécifié. Il est fortement conseillé aux utilisateurs des versions plus anciennes de définir explicitement le filtre connect pour leurs AcceptFilter comme indiqué plus haut.

Voir aussi

  • Protocol

Directive AcceptPathInfo

Description: | Les ressources acceptent des informations sous forme d'un nom de chemin en fin de requête.
Syntaxe: | AcceptPathInfo On|Off|Default
Défaut: | AcceptPathInfo Default
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core

Cette directive permet de définir si les requêtes contenant des informations sous forme d'un nom de chemin suivant le nom d'un fichier réel (ou un fichier qui n'existe pas dans un répertoire qui existe) doivent être acceptées ou rejetées. Les scripts peuvent accéder à cette information via la variable d'environnement PATH_INFO.

Supposons par exemple que /test/ pointe vers un répertoire qui ne contient que le fichier here.html. Les requêtes pour /test/here.html/more et /test/nothere.html/more vont affecter la valeur /more à la variable d'environnement PATH_INFO.

L'argument de la directive AcceptPathInfo possède trois valeurs possibles :

Off
Une requête ne sera acceptée que si elle correspond à un chemin qui existe. Par conséquent, une requête contenant une information de chemin après le nom de fichier réel comme /test/here.html/more dans l'exemple ci-dessus renverra une erreur "404 NOT FOUND".
On
Une requête sera acceptée si la partie principale du chemin correspond à un fichier existant. Dans l'exemple ci-dessus /test/here.html/more, la requête sera acceptée si /test/here.html correspond à un nom de fichier valide.
Default
Le traitement des requêtes est déterminé par le gestionnaire responsable de la requête. Le gestionnaire de base pour les fichiers normaux rejette par défaut les requêtes avec PATH_INFO. Les gestionnaires qui servent des scripts, commecgi-script et isapi-handler, acceptent en général par défaut les requêtes avec PATH_INFO.

Le but premier de la directive AcceptPathInfo est de vous permettre de remplacer le choix du gestionnaire d'accepter ou de rejeter PATH_INFO. Ce remplacement est nécessaire par exemple, lorsque vous utilisez un filtre, comme INCLUDES, pour générer un contenu basé sur PATH_INFO. Le gestionnaire de base va en général rejeter la requête, et vous pouvez utiliser la configuration suivante pour utiliser un tel script :

<Files "mypaths.shtml">
  Options +Includes
  SetOutputFilter INCLUDES
  AcceptPathInfo On
</Files>

Directive AccessFileName

Description: | Nom du fichier de configuration distribué
Syntaxe: | AccessFileName nom-du-fichier [nom-du-fichier] ...
Défaut: | AccessFileName .htaccess
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Au cours du traitement d'une requête, le serveur recherche le premier fichier de configuration existant à partir de la liste de noms dans chaque répertoire composant le chemin du document, à partir du moment où les fichiers de configuration distribués sont activés pour ce répertoire. Par exemple :

AccessFileName .acl

avant de renvoyer le document /usr/local/web/index.html, le serveur va rechercher les fichiers /.acl, /usr/.acl, /usr/local/.acl et /usr/local/web/.acl pour y lire d'éventuelles directives, à moins quelles n'aient été désactivées avec

<Directory "/">
    AllowOverride None
</Directory>

Voir aussi

  • AllowOverride
  • Fichiers de configuration
  • Fichiers .htaccess

Directive AddDefaultCharset

Description: | Paramètre jeu de caractères par défaut à ajouter quand le type de contenu d'une réponse est text/plain ou text/html
Syntaxe: | AddDefaultCharset On|Off|jeu de caractères
Défaut: | AddDefaultCharset Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core

Cette directive spécifie une valeur par défaut pour le paramètre jeu de caractères du type de média (le nom d'un codage de caractères) à ajouter à une réponse, si et seulement si le type de contenu de la réponse est soit text/plain, soit text/html. Ceci va remplacer tout jeu de caractères spécifié dans le corps de la réponse via un élément META, bien que cet effet dépende en fait souvent de la configuration du client de l'utilisateur. La définition de AddDefaultCharset Off désactive cette fonctionnalité. AddDefaultCharset On ajoute un jeu de caractères par défaut de iso-8859-1. Toute autre valeur peut être définie via le paramètre jeu de caractères, qui doit appartenir à la liste des valeurs de jeux de caractères enregistrés par l'IANA à utiliser dans les types de média Internet (types MIME). Par exemple :

AddDefaultCharset utf-8

La directive AddDefaultCharset ne doit être utilisée que lorsque toutes les ressources textes auxquelles elle s'applique possèdent le jeu de caractère spécifié, et qu'il est trop contraignant de définir leur jeu de caractères individuellement. Un exemple de ce type est l'ajout du paramètre jeu de caractères aux ressources comportant un contenu généré, comme les scripts CGI hérités qui peuvent être vulnérables à des attaques de type cross-site scripting à cause des données utilisateurs incluses dans leur sortie. Notez cependant qu'une meilleur solution consiste à corriger (ou supprimer) ces scripts, car la définition d'un jeu de caractères par défaut ne protège pas les utilisateurs qui ont activé la fonctionnalité "Détection automatique de l'encodage des caractères" dans leur navigateur.

Voir aussi

  • AddCharset

Directive AllowEncodedSlashes

Description: | Détermine si les séparateurs de chemin encodés sont autorisés à transiter dans les URLs tels quels
Syntaxe: | AllowEncodedSlashes On|Off|NoDecode
Défaut: | AllowEncodedSlashes Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core
Compatibilité: | L'option NoDecode est disponible depuis la version 2.3.12.

La directive AllowEncodedSlashes permet l'utilisation des URLs contenant des séparateurs de chemin encodés dans la partie chemin (%2F pour / et même %5C pour \ sur les systèmes concernés).

Avec la valeur par défaut, Off, de telles URLs sont refusées et provoquent le renvoi d'une erreur 404 (Not found).

Avec la valeur On, ces URLs sont acceptées, et les slashes encodés sont décodés comme tout autre caractère codé.

Avec la valeur NoDecode, ces URLs sont acceptées, mais les slashes codés ne sont pas décodés et laissés dans leur état codé.

Définir AllowEncodedSlashes à On est surtout utile en association avec PATH_INFO.

Note

Si le codage des slashes dans la partie chemin est nécessaire, l'utilisation de l'option NoDecode est fortement recommandée par mesure de sécurité. Permettre le décodage des slashes pourrait éventuellement induire l'autorisation de chemins non sûrs.

Voir aussi

  • AcceptPathInfo

Directive AllowOverride

Description: | Types de directives autorisées dans les fichiers .htaccess
Syntaxe: | AllowOverride All|None|type directive [type directive] ...
Défaut: | AllowOverride None à partir de la version 2.3.9, AllowOverride All pour les versions antérieures
Contexte: | répertoire
Statut: | Core
Module: | core

Lorsque le serveur trouve un fichier .htaccess (dont le nom est défini par la directive AccessFileName), il doit savoir lesquelles des directives placées dans ce fichier sont autorisées à modifier la configuration préexistante.

Valable seulement dans les sections <Directory>

La directive AllowOverride ne peut être utilisée que dans les sections <Directory> définies sans expressions rationnelles, et non dans les sections <Location>, <DirectoryMatch> ou <Files>.

Lorsque cette directive et la directive AllowOverrideList sont définies à None, les fichiers .htaccess sont totalement ignorés. Dans ce cas, le serveur n'essaiera même pas de lire les fichiers .htaccess du système de fichiers.

Lorsque cette directive est définie à All, toute directive valable dans le Contexte .htaccess sera autorisée dans les fichiers .htaccess.

L'argument type directive peut contenir les groupements de directives suivants (voir ce document pour obtenir la liste à jour des directives activées pour chaque type de directive) :

AuthConfig
Permet l'utilisation des directives d'autorisation (AuthDBMGroupFile, AuthDBMUserFile, AuthGroupFile, AuthName, AuthType, AuthUserFile, Require, etc...).
FileInfo
Permet l'utilisation des directives qui contrôlent les types de documents (directives ErrorDocument, ForceType, LanguagePriority, SetHandler, SetInputFilter, SetOutputFilter, et directives du module mod_mime Add* et Remove*), des metadonnées des documents (Header, RequestHeader, SetEnvIf, SetEnvIfNoCase, BrowserMatch, CookieExpires, CookieDomain, CookieStyle, CookieTracking, CookieName), des directives du module mod_rewrite directives (RewriteEngine, RewriteOptions, RewriteBase, RewriteCond, RewriteRule), des directives du module mod_alias directives (Redirect, RedirectTemp, RedirectPermanent, RedirectMatch), et de la directive Action du module mod_actions.
Indexes
Permet l'utilisation des directives qui contrôlent l'indexation des répertoires (AddDescription, AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, ReadmeName, etc...).
Limit
Permet l'utilisation des directives contrôlant l'accès au serveur (Allow, Deny et Order).
Nonfatal=[Override|Unknown|All]
Permet d'utiliser l'option AllowOverride pour rendre les erreurs de syntaxe non fatales dans les fichiers .htaccess : au lieu de causer une Internal Server Error, les directives non autorisées ou non reconnues seront ignorées et un avertissement enregistré dans le journal :
  • Nonfatal=Override rend les directives interdite par AllowOverride non fatales.
  • Nonfatal=Unknown rend les directives inconnues non fatales. Sont concernées les erreurs de frappe et les directives implémentées par un module non chargé.
  • Nonfatal=All rend toutes les directives précédentes non fatales.

Notez qu'une erreur de syntaxe dans une directive valide causera toujours une internal server error.

Sécurité

Les erreurs non fatales peuvent être à l'origine de problèmes de sécurité pour les utilisateurs de fichiers .htaccess. Par exemple, si AllowOverride interdit AuthConfig, toute configuration utilisateur destinée à restreindre l'accès à un site ne sera pas prise en compte.
Options[=Option,...]
Permet l'utilisation des directives contrôlant les fonctionnalités spécifiques d'un répertoire (Options et XBitHack). "Options" doit être suivi d'un signe "égal", puis d'une liste d'options séparées par des virgules (pas d'espaces) ; ces options doivent être définies à l'aide de la commande Options.

Désactivation implicite des options

Bien que la liste des options disponibles dans les fichiers .htaccess puisse être limitée par cette directive, tant qu'un directive Options est autorisée, toute autre option héritée peut être désactivée en utilisant la syntaxe non-relative. En d'autres termes, ce mécanisme ne peut pas forcer une option spécifique à rester activée tout en permettant à toute autre option d'être activée.

AllowOverride Options=Indexes,MultiViews

Exemple :

AllowOverride AuthConfig Indexes

Dans l'exemple ci-dessus, toutes les directives qui ne font partie ni du groupe AuthConfig, ni du groupe Indexes, provoquent une erreur "internal server error".

Pour des raisons de sécurité et de performance, ne définissez pas AllowOverride à autre chose que None dans votre bloc <Directory "/">. Recherchez plutôt (ou créez) le bloc <Directory> qui se réfère au répertoire où vous allez précisément placer un fichier .htaccess.

Voir aussi

  • AccessFileName
  • AllowOverrideList
  • Fichiers de configuration
  • Fichiers .htaccess
  • Override Class Index for .htaccess

Directive AllowOverrideList

Description: | Directives autorisées dans les fichiers .htaccess
Syntaxe: | AllowOverrideList None|directive [directive-type] ...
Défaut: | AllowOverrideList None
Contexte: | répertoire
Statut: | Core
Module: | core

Lorsque le serveur trouve un fichier .htaccess (comme spécifié par la directive AccessFileName), il doit savoir lesquelles des directives déclarées dans ce fichier peuvent remplacer des directives des fichiers de configuration du serveur.

Seulement disponible dans les sections <Directory>

La directive AllowOverrideList n'est disponible que dans les sections <Directory> spécifiées sans expressions rationnelles.

Lorsque cette directive et la directive AllowOverride sont définies à None, les fichiers .htaccess sont totalement ignorés. Dans ce cas, le serveur ne cherchera même pas à lire des fichiers .htaccess dans le système de fichiers.

Example:

AllowOverride None
AllowOverrideList Redirect RedirectMatch

Dans l'exemple ci-dessus, seules les directives Redirect et RedirectMatch sont autorisées. Toutes les autres provoqueront une erreur interne du serveur.

Example:

AllowOverride AuthConfig
AllowOverrideList CookieTracking CookieName

Dans l'exemple ci-dessus, la directive AllowOverride autorise les directives du groupement AuthConfig, et AllowOverrideList n'autorise que deux directives du groupement FileInfo. Toutes les autres provoqueront une erreur interne du serveur.

Voir aussi

  • AccessFileName
  • AllowOverride
  • Fichiers de configuration
  • Fichiers .htaccess

Directive CGIMapExtension

Description: | Technique permettant de localiser l'interpréteur des scripts CGI
Syntaxe: | CGIMapExtension chemin CGI .extension
Contexte: | répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | NetWare uniquement

Cette directive permet de contrôler la manière dont Apache httpd trouve l'interpréteur servant à exécuter les scripts CGI. Par exemple, avec la définition CGIMapExtension sys:\foo.nlm .foo, tous les fichiers scripts CGI possédant une extension .foo seront passés à l'interpréteur FOO.

Directive CGIPassAuth

Description: | Active la transmission d'en-têtes d'autorisation HTTP aux scripts en tant que variables CGI
Syntaxe: | CGIPassAuth On|Off
Défaut: | CGIPassAuth Off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Core
Module: | core
Compatibilité: | Disponible à partir de la version 2.4.13 du serveur HTTP Apache

La directive CGIPassAuth permet aux scripts d'accéder aux en-têtes d'autorisation HTTP tels que Authorization, en-tête nécessaire aux scripts qui implémente une authentification HTTP de base. Normalement, ces en-têtes HTTP sont invisibles pour les scripts car ils leurs permettraient de voir les identifiants et mots de passe utilisés pour accéder au serveur lorsque l'authentification HTTP de base est activée au niveau du serveur web. Cette directive doit être définie à "On" lorsque des scripts sont autorisés à implémenter une authentification HTTP de base.

Cette directive constitue une alternative à l'option de compilation SECURITY_HOLE_PASS_AUTHORIZATION qui était déjà disponible dans les versions précédentes du serveur HTTP Apache.

Cette option est prise en compte par tout module qui utilise ap_add_common_vars(), comme mod_cgi, mod_cgid, mod_proxy_fcgi, mod_proxy_scgi, etc... En particulier, elle affecte les modules qui ne traitent pas à proprement parler les requêtes, mais utilisent quand-même cette API, comme mod_include ou mod_ext_filter. Les modules tiers qui n'utilisent pas ap_add_common_vars() peuvent aussi choisir de prendre en compte cette option.

Directive CGIVar

Description: | Contrôle la manière dont certaines variables CGI sont définies
Syntaxe: | CGIVar variable rule
Contexte: | répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | Disponible à partir de la version 2.4.21 du serveur HTTP Apache

Cette directive permet de contrôler la manière dont certaines variables CGI sont définies.

règles REQUEST_URI :

original-uri (valeur par défaut)
La valeur est extraite de la requête originale, et ne tient pas compte des redirections internes ou des sous-requêtes qui pourraient modifier la ressource demandée.
current-uri
La valeur reflète la ressource en cours de traitement ; elle peut être différente de la ressource demandée dans la requête initiale du client suite à d'éventuelles redirections internes ou sous-requêtes.

Directive ContentDigest

Description: | Active la génération d'un en-tête Content-MD5 dans la réponse HTTP
Syntaxe: | ContentDigest On|Off
Défaut: | ContentDigest Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Core
Module: | core

Cette directive active la génération d'un en-tête Content-MD5 selon les définitions des RFC 1864 et 2616.

MD5 est un algorithme permettant de générer un condensé (parfois appelé "empreinte") à partir de données d'une taille aléatoire ; le degré de précision est tel que la moindre altération des données d'origine entraîne une altération de l'empreinte.

L'en-tête Content-MD5 permet de vérifier l'intégrité de la réponse HTTP dans son ensemble. Un serveur mandataire ou un client peut utiliser cet en-tête pour rechercher une éventuelle modification accidentelle de la réponse au cours de sa transmission. Exemple d'en-tête :

Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==

Notez que des problèmes de performances peuvent affecter votre serveur, car l'empreinte est générée pour chaque requête (il n'y a pas de mise en cache).

L'en-tête Content-MD5 n'est envoyé qu'avec les documents servis par le module core, à l'exclusion de tout autre module. Ainsi, les documents SSI, les sorties de scripts CGI, et les réponses à des requêtes partielles (byte range) ne comportent pas cet en-tête.

Directive DefaultRuntimeDir

Description: | Répertoire de base des fichiers créés au cours de l'exécution du serveur
Syntaxe: | DefaultRuntimeDir chemin-répertoire
Défaut: | DefaultRuntimeDir DEFAULT_REL_RUNTIMEDIR (logs/)
Contexte: | configuration du serveur
Statut: | Core
Module: | core
Compatibilité: | Disponible depuis la version 2.4.2 du serveur HTTP Apache

La directive DefaultRuntimeDir permet de définir le répertoire dans lequel le serveur va créer les différents fichiers relatifs à son exécution (mémoire partagée, verrous, etc...). Si le chemin spécifié est relatif, le chemin absolu sera généré relativement à la valeur de la directive ServerRoot

Example

DefaultRuntimeDir scratch/

La valeur par défaut de la directive DefaultRuntimeDir peut être modifiée en changeant la valeur de la macro DEFAULT_REL_RUNTIMEDIR définie à la compilation.

Note: si la valeur de ServerRoot n'a pas été spécifiée avant d'utiliser cette directive, c'est la valeur par défaut de ServerRoot qui sera utilisée pour définir la base du répertoire.

Voir aussi

  • Voir les conseils à propos de sésurité pour plus d'informations en vue de définir correctement les permissions sur la racine du serveur ServerRoot

Directive DefaultType

Description: | Les seuls effets de cette directive sont des émissions d'avertissements si sa valeur est différente de none. Dans les versions précédentes, DefaultType permettait de spécifier un type de média à assigner par défaut au contenu d'une réponse pour lequel aucun autre type de média n'avait été trouvé.
Syntaxe: | DefaultType type média|none
Défaut: | DefaultType none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | L'argument none est disponible dans les versions d'Apache httpd 2.2.7 et supérieures. Tous les autres choix sont DESACTIVÉS à partir des version 2.3.x.

Cette directive a été désactivée. Pour la compatibilité ascendante avec les anciens fichiers de configuration, elle peut être spécifiée avec la valeur none, c'est à dire sans type de médium par défaut. Par exemple :

DefaultType None

DefaultType None n'est disponible que dans les versions d'Apache 2.2.7 et supérieures.

Utilisez le fichier de configuration mime.types et la directive AddType pour configurer l'assignement d'un type de médium via les extensions de fichiers, ou la directive ForceType pour attribuer un type de médium à des ressources spécifiques. Dans le cas contraire, le serveur enverra sa réponse sans champ d'en-tête Content-Type, et le destinataire devra déterminer lui-même le type de médium.

Directive Define

Description: | Permet de définir une variable
Syntaxe: | Define nom-paramètre [valeur-paramètre]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core

Avec un seul paramètre, l'effet de la directive Define est identique à celui de l'argument -D du programme httpd. Il permet de modifier le comportement des sections <IfDefine> sans avoir à ajouter d'argument -D au sein des scripts de démarrage.

De plus, le second paramètre permet d'affecter une valeur à la variable définie par le premier. Cette variable peut être référencée dans le fichier de configuration via la syntaxe ${VAR}. La portée de la variable est toujours globale, et n'est jamais limitée à la section de configuration courante.

<IfDefine TEST>
  Define servername test.example.com
</IfDefine>
<IfDefine !TEST>
  Define servername www.example.com
  Define SSL
</IfDefine>

DocumentRoot "/var/www/${servername}/htdocs"

Le caractère ":" est interdit dans les noms de variables afin d'éviter les conflits avec la syntaxe de la directive RewriteMap.

Portée de la directive et pièges à éviter

Si cette directive est définie au sein d'un bloc VirtualHost, les changements qu'elle induit sont visibles de toute directive ultérieure, au delà de tout bloc VirtualHost.

Voir aussi

  • UnDefine
  • IfDefine

Directive <Directory>

Description: | Regroupe un ensemble de directives qui ne s'appliquent qu'au répertoire concerné du système de fichiers, à ses sous-répertoires, et à leur contenu.
Syntaxe: | <Directory chemin répertoire> ... </Directory>
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Les balises <Directory> et </Directory> permettent de regrouper un ensemble de directives qui ne s'appliquent qu'au répertoire précisé, à ses sous-répertoires, et aux fichiers situés dans ces sous-répertoires. Toute directive autorisée dans un contexte de répertoire peut être utilisée. chemin répertoire est soit le chemin absolu d'un répertoire, soit une chaîne de caractères avec caractères génériques utilisant la comparaison Unix de style shell. Dans une chaîne de caractères avec caractères génériques, ? correspond à un caractère quelconque, et * à toute chaîne de caractères. Les intervalles de caractères [] sont aussi autorisés. Aucun caractère générique ne peut remplacer le caractère `/', si bien que l'expression <Directory "/*/public_html"> ne conviendra pas pour le chemin * /home/user/public_html, alors que <Directory "/home/*/public_html"> conviendra. Exemple :

<Directory "/usr/local/httpd/htdocs">
  Options Indexes FollowSymLinks
</Directory>

Les chemins de répertoires contenant des espaces doivent être entourés de guillemets afin d'empêcher l'interprétation de ces espaces comme fins d'arguments.

Soyez prudent avec l'argument chemin répertoire : il doit correspondre exactement au chemin du système de fichier qu'Apache httpd utilise pour accéder aux fichiers. Les directives comprises dans une section <Directory> ne s'appliqueront pas aux fichiers du même répertoire auxquels on aura accédé via un chemin différent, per exemple via un lien symbolique.

Les Expressions rationnelles peuvent aussi être utilisées en ajoutant le caractère ~. Par exemple :

<Directory ~ "^/www/[0-9]{3}">

</Directory>

pourra correspondre à tout répertoire situé dans /www/ et dont le nom se compose de trois chiffres.

Si plusieurs sections <Directory> (sans expression rationnelle) correspondent au répertoire (ou à un de ses parents) qui contient le document, les directives de la section <Directory> dont le chemin est le plus court sont appliquées en premier, en s'intercalant avec les directives des fichiers .htaccess. Par exemple, avec

<Directory "/">
  AllowOverride None
</Directory>

<Directory "/home">
  AllowOverride FileInfo
</Directory>

l'accès au document /home/web/dir/doc.html emprunte le chemin suivant :

  • Aplication de la directive AllowOverride None (qui désactive les fichiers .htaccess).
  • Application de la directive AllowOverride FileInfo (pour le répertoire /home).
  • Application de toute directive FileInfo qui se trouverait dans d'éventuels fichiers /home/.htaccess, /home/web/.htaccess ou /home/web/dir/.htaccess, dans cet ordre.

Les directives associées aux répertoires sous forme d'expressions rationnelles ne sont prises en compte qu'une fois toutes les directives des sections sans expressions rationnelles appliquées. Alors, tous les répertoires avec expressions rationnelles sont testés selon l'ordre dans lequel ils apparaissent dans le fichier de configuration. Par exemple, avec

<Directory ~ "abc$">
  # ... directives ici ...
</Directory>

la section avec expression rationnelle ne sera prise en compte qu'après les sections <Directory> sans expression rationnelle et les fichiers .htaccess. Alors, l'expression rationnelle conviendra pour /home/abc/public_html/abc et la section <Directory> correspondante s'appliquera.

Notez que la politique d'accès par défaut dans les sections <Directory "/"> consiste à autoriser tout accès sans restriction. Ceci signifie qu'Apache httpd va servir tout fichier correspondant à une URL. Il est recommandé de modifier cette situation à l'aide d'un bloc du style

<Directory "/">
  Require all denied
</Directory>

puis d'affiner la configuration pour les répertoires que vous voulez rendre accessibles. Voir la page Conseils à propos de sécurité pour plus de détails.

Les sections <Directory> se situent dans le fichier httpd.conf. Les directives <Directory> ne peuvent pas être imbriquées et ne sont pas autorisées dans les sections <Limit> ou <LimitExcept>.

Voir aussi

  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour des explications à propos de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête

Directive <DirectoryMatch>

Description: | Regroupe des directives qui s'appliquent au contenu de répertoires du système de fichiers correspondant à une expression rationnelle
Syntaxe: | <DirectoryMatch regex> ... </DirectoryMatch>
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Les balises <DirectoryMatch> et </DirectoryMatch> permettent de regrouper un ensemble de directives qui ne s'appliqueront qu'au répertoire précisé (et aux fichiers qu'il contient), comme pour la section <Directory>. Cependant, le répertoire est précisé sous la forme d'une expression rationnelle. Par exemple :

<DirectoryMatch "^/www/(.+/)?[0-9]{3}/">
    # ...
</DirectoryMatch>

convient pour les sous-répertoires de /www/ dont le nom se compose de trois chiffres.

Compatibilité

Avant la version 2.3.9, cette directive s'appliquait aussi aux sous-répertoires (comme la directive <Directory>), et ne tenait pas compte du symbole de fin de ligne ($). Depuis la version 2.3.9, seuls les répertoires qui correspondent à l'expression sont affectés par les directives contenues dans la section.

slash de fin

Cette directive s'applique aux requêtes pour des répertoires avec ou sans slash de fin ; les expressions contenant un symbole de fin de ligne ($) doivent donc faire l'objet d'une attention particulière.

A partir de la version 2.4.8, les groupes nommés et les références arrières sont extraits et enregistrés dans l'environnement avec leur nom en majuscules et préfixé par "MATCH_". Ceci permet de référencer des URLs dans des expressions ou au sein de modules comme mod_rewrite. Pour éviter toute confusion, les références arrières numérotées (non nommées) sont ignorées. Vous devez utiliser à la place des groupes nommés.

<DirectoryMatch "^/var/www/combined/(?<sitename>[^/]+)">
    Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</DirectoryMatch>

Voir aussi

  • <Directory> pour une description de la manière dont les expressions rationnelles sont traitées en présence d'autres sections <Directory> sans expressions rationnelles
  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour une explication à propos de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête

Directive DocumentRoot

Description: | Racine principale de l'arborescence des documents visible depuis Internet
Syntaxe: | DocumentRoot chemin répertoire
Défaut: | DocumentRoot "/usr/local/apache/htdocs"
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Cette directive permet de définir le répertoire à partir duquel httpd va servir les fichiers. S'il ne correspond pas à un Alias, le chemin de l'URL sera ajouté par le serveur à la racine des documents afin de construire le chemin du document recherché. Exemple :

DocumentRoot "/usr/web"

un accès à http://my.example.com/index.html se réfère alors à /usr/web/index.html. Si chemin répertoire n'est pas un chemin absolu, il est considéré comme relatif au chemin défini par la directive ServerRoot.

Le répertoire défini par la directive DocumentRoot ne doit pas comporter de slash final.

Voir aussi

  • Mise en correspondance des URLs avec le système de fichiers

Directive <Else>

Description: | Contient des directives qui ne s'appliquent que si la condition correspondant à la section <If> ou <ElseIf> précédente n'est pas satisfaite par la requête à l'exécution
Syntaxe: | <Else> ... </Else>
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core
Compatibilité: | Les conditions imbriquées sont supportées à partir de la version 2.4.26 du serveur HTTP Apache

La section <Else> applique les directives qu'elle contient si et seulement si les conditions correspondant à la section <If> ou <ElseIf> immédiatement supérieure et dans la même portée n'ont pas été satisfaites. Par exemple, dans :

<If "-z req('Host')">
  # ...
</If>
<Else>
  # ...
</Else>

La condition de la section <If> serait satisfaite pour les requêtes HTTP/1.0 sans en-tête Host:, alors que celle de la section <Else> le serait pour les requêtes comportant un en-tête Host:.

Voir aussi

  • <If>
  • <ElseIf>
  • Fonctionnement des sections <Directory>, <Location>, <Files> pour une explication de la manière dont ces différentes section se combinent entre elles lorsqu'une requête est reçue. Les directives <If>, <ElseIf>, et <Else> s'appliquent en dernier.

Directive <ElseIf>

Description: | Contient des directives qui ne s'appliquent que si la condition correspondante est satisfaite par une requête à l'exécution, alors que la condition correspondant à la section <If> ou <ElseIf> précédente ne l'était pas.
Syntaxe: | <ElseIf expression> ... </ElseIf>
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core
Compatibilité: | Les conditions imbriquées sont supportées à partir de la version 2.4.26 du serveur HTTP Apache

La section <ElseIf> applique les directives qu'elle contient si et seulement si d'une part la condition correspondante est satisfaite, et d'autre part la condition correspondant à la section <If> ou <ElseIf> de la même portée ne l'est pas. Par exemple, dans :

<If "-R '10.1.0.0/16'">
  #...
</If>
<ElseIf "-R '10.0.0.0/8'">
  #...
</ElseIf>
<Else>
  #...
</Else>

La condition correspondant à la section <ElseIf> est satisfaite si l'adresse distante de la requête appartient au sous-réseau 10.0.0.0/8, mais pas si elle appartient au sous-réseau 10.1.0.0/16.

Voir aussi

  • Les expressions dans le serveur HTTP Apache, pour une référence complète et d'autres exemples.
  • <If>
  • <Else>
  • Fonctionnement des sections <Directory>, <Location>, <Files> pour une explication de la manière dont ces différentes section se combinent entre elles lorsqu'une requête est reçue. Les directives <If>, <ElseIf>, et <Else> s'appliquent en dernier.

Directive EnableMMAP

Description: | Utilise la projection en mémoire (Memory-Mapping) pour lire les fichiers pendant qu'ils sont servis
Syntaxe: | EnableMMAP On|Off
Défaut: | EnableMMAP On
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core

Cette directive définit si httpd peut utiliser la projection en mémoire (Memory-Mapping) quand il doit lire le contenu d'un fichier pendant qu'il est servi. Par défaut, lorsque le traitement d'une requête requiert l'accès aux données contenues dans un fichier -- par exemple, pour servir un fichier interprété par le serveur à l'aide de mod_include -- Apache httpd projette le fichier en mémoire si le système d'exploitation le permet.

Cette projection en mémoire induit parfois une amélioration des performances. Sur certains systèmes cependant, il est préférable de désactiver la projection en mémoire afin d'éviter certains problèmes opérationnels :

  • Sur certains systèmes multi-processeurs, la projection en mémoire peut dégrader les performances du programme httpd.
  • S'il fait l'objet d'une projection en mémoire par httpd, la suppression ou la troncature d'un fichier peut provoquer un crash de httpd avec une erreur de segmentation.

Pour les configurations de serveur sujettes à ce genre de problème, il est préférable de désactiver la projection en mémoire des fichiers servis en spécifiant :

EnableMMAP Off

Pour les montages NFS, cette fonctionnalité peut être explicitement désactivée pour les fichiers concernés en spécifiant :

<Directory "/path-to-nfs-files">
  EnableMMAP Off
</Directory>

Directive EnableSendfile

Description: | Utilise le support sendfile du noyau pour servir les fichiers aux clients
Syntaxe: | EnableSendfile On|Off
Défaut: | EnableSendfile Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | Par défaut à Off depuis la version 2.3.9.

Cette directive définit si le programme httpd peut utiliser le support sendfile du noyau pour transmettre le contenu des fichiers aux clients. Par défaut, lorsque le traitement d'une requête ne requiert pas l'accès aux données contenues dans un fichier -- par exemple, pour la transmission d'un fichier statique -- Apache httpd utilise sendfile pour transmettre le contenu du fichier sans même lire ce dernier, si le système d'exploitation le permet.

Ce mécanisme sendfile évite la séparation des opérations de lecture et d'envoi, ainsi que les réservations de tampons. sur certains systèmes cependant, ou sous certains systèmes de fichiers, il est préférable de désactiver cette fonctionnalité afin d'éviter certains problèmes opérationnels :

  • Certains systèmes peuvent présenter un support sendfile défectueux que le système de compilation n'a pas détecté, en particulier si les exécutables ont été compilés sur une autre machine, puis copiés sur la première avec un support sendfile défectueux.
  • Sous Linux, l'utilisation de sendfile induit des bogues lors de la récupération des paquets de vérification TCP (TCP-checksum) avec certaines cartes réseau lorsqu'on utilise IPv6.
  • Sous Linux sur Itanium, sendfile peut s'avérer incapable de traiter les fichiers de plus de 2 Go.
  • Avec un montage réseau de DocumentRoot (par exemple NFS, SMB, CIFS, FUSE), le noyau peut s'avérer incapable de servir un fichier de ce montage réseau en passant par son propre cache.

Pour les configurations de serveur non sujettes à ce genre de problème, vous pouvez activer cette fonctionnalité en spécifiant :

EnableSendfile On

Pour les montages réseau, cette fonctionnalité peut être explicitement désactivée pour les fichiers concernés en spécifiant :

<Directory "/path-to-nfs-files">
  EnableSendfile Off
</Directory>

Veuillez noter que la configuration de la directive EnableSendfile dans un contexte de répertoire ou de fichier .htaccess n'est pas supportée par mod_cache_disk. Le module ne prend en compte la définition de EnableSendfile que dans un contexte global.

Directive Error

Description: | Interrompt la lecture de la configuration avec un message d'erreur personnalisé
Syntaxe: | Error message
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Core
Module: | core
Compatibilité: | à partir de la version 2.3.9

Si une erreur peut être détectée dans la configuration, souvent un module manquant, cette directive peut être utilisée pour générer un message d'erreur personnalisé, et interrompre la lecture de la configuration.

# Exemple
# vérification du chargement de mod_include
<IfModule !include_module>
  Error "mod_include is required by mod_foo.  Load it with LoadModule."
</IfModule>

# vérification de la définition de SSL ou (exclusif) NOSSL
<IfDefine SSL>
<IfDefine NOSSL>
  Error "Both SSL and NOSSL are defined.  Define only one of them."
</IfDefine>
</IfDefine>
<IfDefine !SSL>
<IfDefine !NOSSL>
  Error "Either SSL or NOSSL must be defined."
</IfDefine>
</IfDefine>

Directive ErrorDocument

Description: | Document que le serveur renvoie au client en cas d'erreur
Syntaxe: | ErrorDocument code erreur document
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core

Apache httpd peut traiter les problèmes et les erreurs de quatre manières,

  1. afficher un simple message d'erreur au contenu fixe
  2. afficher un message personnalisé
  3. rediriger en interne vers un chemin d'URL local pour traiter le problème ou l'erreur
  4. rediriger vers une URL externe pour traiter le problème ou l'erreur

La première option constitue le comportement par défaut; pour choisir une des trois autres options, il faut configurer Apache à l'aide de la directive ErrorDocument, suivie du code de la réponse HTTP et d'une URL ou d'un message. Apache httpd fournit parfois des informations supplémentaires à propos du problème ou de l'erreur.

A partir de la version 2.4.13, il est possible d'utiliser la syntaxe des expressions dans cette directive afin de générer des chaînes et URLs dynamiques.

Les URLs peuvent commencer par un slash (/) pour les chemins web locaux (relatifs au répertoire défini par la directive DocumentRoot), ou se présenter sous la forme d'une URL complète que le client pourra résoudre. Alternativement, un message à afficher par le navigateur pourra être fourni. Notez que la décision de considérer le paramètre comme URL, chemin ou message intervient avant toute interprètation d'expression. Exemples :

ErrorDocument 500 http://example.com/cgi-bin/server-error.cgi
ErrorDocument 404 /errors/bad_urls.php
ErrorDocument 401 /subscription_info.html
ErrorDocument 403 "Sorry can't allow you access today"
ErrorDocument 403 Forbidden!
ErrorDocument 403 /errors/forbidden.py?referrer=%{escape:%{HTTP_REFERER}}

De plus, on peut spécifier la valeur spéciale default pour indiquer l'utilisation d'un simple message d'Apache httpd codé en dur. Bien que non nécessaire dans des circonstances normales, la spécification de la valeur default va permettre de rétablir l'utilisation du simple message d'Apache httpd codé en dur pour les configurations qui sans cela, hériteraient d'une directive ErrorDocument existante.

ErrorDocument 404 /cgi-bin/bad_urls.pl

<Directory "/web/docs">
  ErrorDocument 404 default
</Directory>

Notez que lorsque vous spécifiez une directive ErrorDocument pointant vers une URL distante (c'est à dire tout ce qui commence par le préfixe http), le serveur HTTP Apache va envoyer une redirection au client afin de lui indiquer où trouver le document, même dans le cas où ce document se trouve sur le serveur local. Ceci a de nombreuses conséquences dont la plus importante réside dans le fait que le client ne recevra pas le code d'erreur original, mais au contraire un code de statut de redirection. Ceci peut en retour semer la confusion chez les robots web et divers clients qui tentent de déterminer la validité d'une URL en examinant le code de statut. De plus, si vous utilisez une URL distante avec ErrorDocument 401, le client ne saura pas qu'il doit demander un mot de passe à l'utilisateur car il ne recevra pas le code de statut 401. C'est pourquoi, si vous utilisez une directive ErrorDocument 401, elle devra faire référence à un document par le biais d'un chemin local.

Microsoft Internet Explorer (MSIE) ignore par défaut les messages d'erreur générés par le serveur lorsqu'ils sont trop courts et remplacent ses propres messages d'erreur "amicaux". Le seuil de taille varie en fonction du type d'erreur, mais en général, si la taille de votre message d'erreur est supérieure à 512 octets, il y a peu de chances pour que MSIE l'occulte, et il sera affiché par ce dernier. Vous trouverez d'avantage d'informations dans l'article de la base de connaissances Microsoft Q294807.

Bien que la plupart des messages d'erreur internes originaux puissent être remplacés, ceux-ci sont cependant conservés dans certaines circonstances sans tenir compte de la définition de la directive ErrorDocument. En particulier, en cas de détection d'une requête mal formée, le processus de traitement normal des requêtes est immédiatement interrompu, et un message d'erreur interne est renvoyé, ceci afin de se prémunir contre les problèmes de sécurité liés aux requêtes mal formées.

Si vous utilisez mod_proxy, il est en général préférable d'activer ProxyErrorOverride afin d'être en mesure de produire des messages d'erreur personnalisés pour le compte de votre serveur d'origine. Si vous n'activez pas ProxyErrorOverride, Apache httpd ne générera pas de messages d'erreur personnalisés pour le contenu mandaté.

Voir aussi

  • documentation sur la personnalisation des réponses

Directive ErrorLog

Description: | Définition du chemin du journal des erreurs
Syntaxe: | ErrorLog file-path|syslog[:[facility][:tag]]
Défaut: | ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive ErrorLog permet de définir le nom du fichier dans lequel le serveur va journaliser toutes les erreurs qu'il rencontre. Si le file-path n'est pas absolu, il est considéré comme relatif au chemin défini par la directive ServerRoot.

ErrorLog "/var/log/httpd/error_log"

Si le file-path commence par une barre verticale "(|)", il est considéré comme une commande à lancer pour traiter la journalisation de l'erreur.

ErrorLog "|/usr/local/bin/httpd_errors"

Voir les notes à propos des journaux redirigés pour plus d'informations.

L'utilisation de syslog à la place d'un nom de fichier active la journalisation via syslogd(8) si le système le supporte. Le dispositif syslog par défaut est local7, mais vous pouvez le modifier à l'aide de la syntaxe syslog:facility, où facility peut être remplacé par un des noms habituellement documentés dans la page de man syslog(1). Le dispositif syslog local7 est global, et si il est modifié dans un serveur virtuel, le dispositif final spécifié affecte l'ensemble du serveur. La même règle s'applique au tag syslog qui utilise par défaut le nom du binaire du serveur HTTP Apache httpd dans la plupart des cas. Vous pouvez aussi modifier cette valeur en utilisant la syntaxe syslog::tag.

ErrorLog syslog:user
ErrorLog syslog:user:httpd.srv1
ErrorLog syslog::httpd.srv2

Des modules supplémentaires peuvent fournir leurs propres fournisseurs ErrorLog. La syntaxe est similaire à celle de l'exemple syslog ci-dessus.

SECURITE : Voir le document conseils à propos de sécurité pour des détails sur les raisons pour lesquelles votre sécurité peut être compromise si le répertoire contenant les fichiers journaux présente des droits en écriture pour tout autre utilisateur que celui sous lequel le serveur est démarré.

Note

Lors de la spécification d'un chemin de fichier sur les plates-formes non-Unix, on doit veiller à n'utiliser que des slashes (/), même si la plate-forme autorise l'utilisation des anti-slashes (\). Et d'une manière générale, il est recommandé de n'utiliser que des slashes (/) dans les fichiers de configuration.

Voir aussi

  • LogLevel
  • Fichiers journaux du serveur HTTP Apache

Directive ErrorLogFormat

Description: | Spécification du format des entrées du journal des erreurs
Syntaxe: | ErrorLogFormat [connection|request] format
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive ErrorLogFormat permet de spécifier quelles informations supplémentaires vont être enregistrées dans le journal des erreurs en plus du message habituel.

# Exemple simple
ErrorLogFormat "[%t] [%l] [pid %P] %F: %E: [client %a] %M"

La spécification de connection ou request comme premier paramètre permet de définir des formats supplémentaires, ce qui a pour effet de journaliser des informations additionnelles lorsque le premier message est enregistré respectivement pour une connexion ou une requête spécifique. Ces informations additionnelles ne sont enregistrées qu'une seule fois par connexion/requête. Si le traitement d'une connexion ou d'une requête ne génère aucun message dans le journal, alors aucune information additionnelle n'est enregistrée.

Il peut arriver que certains items de la chaîne de format ne produisent aucune sortie. Par exemple, l'en-tête Referer n'est présent que si le message du journal est associé à une requête et s'il est généré à un moment où l'en-tête Referer a déjà été lu par le client. Si aucune sortie n'est générée, le comportement par défaut consiste à supprimer tout ce qui se trouve entre l'espace précédent et le suivant. Ceci implique que la ligne de journalisation est divisée en champs ne contenant pas d'espace séparés par des espaces. Si un item de la chaîne de format ne génère aucune sortie, l'ensemble du champ est omis. Par exemple, si l'adresse distante %a du format [%t] [%l] [%a] %M  n'est pas disponible, les crochets qui l'entourent ne seront eux-mêmes pas enregistrés. Il est possible d'échapper les espaces par un anti-slash afin qu'ils ne soient pas considérés comme séparateurs de champs. La combinaison '% ' (pourcentage espace) est un délimiteur de champ de taille nulle qui ne génère aucune sortie.

Ce comportement peut être changé en ajoutant des modificateurs à l'item de la chaîne de format. Le modificateur - (moins) provoque l'enregistrement d'un signe moins si l'item considéré ne génère aucune sortie. Pour les formats à enregistrement unique par connexion/requête, il est aussi possible d'utiliser le modificateur + (plus). Si un item ne générant aucune sortie possède le modificateur plus, la ligne dans son ensemble est omise.

Un modificateur de type entier permet d'assigner un niveau de sévérité à un item de format. L'item considéré ne sera journalisé que si la sévérité du message n'est pas plus haute que le niveau de sévérité spécifié. Les valeurs possibles vont de 1 (alert) à 15 (trace8), en passant par 4 (warn) ou 7 (debug).

Par exemple, voici ce qui arriverait si vous ajoutiez des modificateurs à l'item %{Referer}i qui enregistre le contenu de l'en-tête Referer.

Item modifié | Signification
%-{Referer}i | Enregistre le caractère - si l'en-tête Referer n'est pas défini.
%+{Referer}i | N'enregistre rien si l'en-tête Referer n'est pas défini.
%4{Referer}i | N'enregistre le contenu de l'en-tête Referer que si la sévérité du message de journalisation est supérieure à 4.

Certains items de format acceptent des paramètres supplémentaires entre accolades.

Chaîne de format | Description
%% | Le signe pourcentage
%a | Adresse IP et port clients
%{c}a | Port et adresse IP sous-jacents du correspondant pour la connexion (voir le module mod_remoteip)
%A | Adresse IP et port locaux
%{name}e | Variable d'environnement de requête name
%E | Etat d'erreur APR/OS et chaîne
%F | Nom du fichier source et numéro de ligne de l'appel du journal
%{name}i | En-tête de requête name
%k | Nombre de requêtes persistantes pour cette connexion
%l | Sévérité du message
%L | Identifiant journal de la requête
%{c}L | Identifiant journal de la connexion
%{C}L | Identifiant journal de la connexion si utilisé dans la portée de la connexion, vide sinon
%m | Nom du module qui effectue la journalisation du message
%M | Le message effectif
%{name}n | Note de requête name
%P | Identifiant du processus courant
%T | Identifiant du thread courant
%{g}T | Identifiant unique de thread système du thread courant (l'identifiant affiché par la commande top par exemple ; seulement sous Linux pour l'instant)
%t | L'heure courante
%{u}t | L'heure courante avec les microsecondes
%{cu}t | L'heure courante au format compact ISO 8601, avec les microsecondes
%v | Le nom de serveur canonique ServerName du serveur courant.
%V | Le nom de serveur du serveur qui sert la requête en accord avec la définition de la directive UseCanonicalName.
\ (anti-slash espace) | Espace non délimiteur
% (pourcentage espace) | Délimiteur de champ (aucune sortie)

L'item de format identifiant journal %L génère un identifiant unique pour une connexion ou une requête. Il peut servir à déterminer quelles lignes correspondent à la même connexion ou requête ou quelle requête est associée à tel connexion. Un item de format %L est aussi disponible dans le module mod_log_config, mais il permet dans ce contexte de corréler les entrées du journal des accès avec celles du journal des erreurs. Si le module mod_unique_id est chargé, c'est son identifiant unique qui sera utilisé comme identifiant de journal pour les requêtes.

# Exemple (format par défaut pour les MPMs threadés)
ErrorLogFormat "[%{u}t] [%-m:%l] [pid %P:tid %T] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i"

Cet exemple renverrait un message d'erreur du style :

[Thu May 12 08:28:57.652118 2011] [core:error] [pid 8777:tid 4326490112] [client ::1:58619] File does not exist: /usr/local/apache2/htdocs/favicon.ico

Notez que, comme indiqué plus haut, certains champs sont totalement supprimés s'ils n'ont pas été définis.

# Exemple (similaire au format 2.2.x)
ErrorLogFormat "[%t] [%l] %7F: %E: [client\ %a] %M% ,\ referer\ %{Referer}i"
# Exemple avancé avec identifiants journal de requête/connexion
ErrorLogFormat "[%{uc}t] [%-m:%-l] [R:%L] [C:%{C}L] %7F: %E: %M"
ErrorLogFormat request "[%{uc}t] [R:%L] Request %k on C:%{c}L pid:%P tid:%T"
ErrorLogFormat request "[%{uc}t] [R:%L] UA:'%+{User-Agent}i'"
ErrorLogFormat request "[%{uc}t] [R:%L] Referer:'%+{Referer}i'"
ErrorLogFormat connection "[%{uc}t] [C:%{c}L] local\ %a remote\ %A"

Voir aussi

  • ErrorLog
  • LogLevel
  • Fichiers journaux du serveur HTTP Apache

Directive ExtendedStatus

Description: | Extrait des informations d'état étendues pour chaque requête
Syntaxe: | ExtendedStatus On|Off
Défaut: | ExtendedStatus Off
Contexte: | configuration du serveur
Statut: | Core
Module: | core

Cette option permet d'extraire des données supplémentaires concernant la requête en cours de traitement pour un processus donné, et crée un résumé d'utilisation ; vous pouvez accéder à ces variables pendant l'exécution en configurant mod_status. Notez que d'autres modules sont susceptibles de s'appuyer sur ce tableau de bord.

Cette directive s'applique au serveur dans son ensemble, et ne peut pas être activée/désactivée pour un serveur virtuel particulier. Notez que l'extraction des informations d'état étendues peut ralentir le serveur. Notez aussi que cette définition ne peut pas être modifiée au cours d'un redémarrage graceful.

Notez que le chargement de mod_status définit automatiquement ExtendedStatus à On, et que d'autres modules tiers sont susceptibles d'en faire de même. De tels modules ont besoin d'informations détaillées à propos de l'état de tous les processus. Depuis la version 2.3.6, mod_status a définit la valeur par défaut à On, alors qu'elle était à Off dans les versions antérieures.

Directive FileETag

Description: | Caractéristiques de fichier utilisées lors de la génération de l'en-tête de réponse HTTP ETag pour les fichiers statiques
Syntaxe: | FileETag composant ...
Défaut: | FileETag MTime Size
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | La valeur par défaut était "INode MTime Size" dans les versions 2.3.14 et antérieures.

La directive FileETag définit les caractéristiques de fichier utilisées lors de la génération de l'en-tête de réponse HTTP ETag (entity tag) quand le document est contenu dans un fichier statique(la valeur de ETag est utilisée dans le cadre de la gestion du cache pour préserver la bande passante réseau). La directive FileETag vous permet maintenant de choisir quelles caractéristiques du fichier vont être utilisées, le cas échéant. Les mots-clés reconnus sont :

INode
Le numéro d'i-node du fichier sera inclus dans le processus de génération
MTime
La date et l'heure auxquelles le fichier a été modifié la dernière fois seront incluses
Size
La taille du fichier en octets sera incluse
All
Tous les champs disponibles seront utilisés. Cette définition est équivalente à :
FileETag INode MTime Size
None
Si le document se compose d'un fichier, aucun champ ETag ne sera inclus dans la réponse

Les mots-clés INode, MTime, et Size peuvent être préfixés par + ou -, ce qui permet de modifier les valeurs par défaut héritées d'un niveau de configuration plus général. Tout mot-clé apparaissant sans aucun préfixe annule entièrement et immédiatement les configurations héritées.

Si la configuration d'un répertoire contient FileETag INode MTime Size, et si un de ses sous-répertoires contient FileETag -INode, la configuration de ce sous-répertoire (qui sera propagée vers tout sous-répertoire qui ne la supplante pas), sera équivalente à FileETag MTime Size.

Avertissement

Ne modifiez pas les valeurs par défaut pour les répertoires ou localisations où WebDAV est activé et qui utilisent mod_dav_fs comme fournisseur de stockage. mod_dav_fs utilise MTime Size comme format fixe pour les comparaisons de champs ETag dans les requêtes conditionnelles. Ces requêtes conditionnelles échoueront si le format ETag est modifié via la directive FileETag.

Inclusions côté serveur

Aucun champ ETag n'est généré pour les réponses interprétées par mod_include, car l'entité de la réponse peut changer sans modification de l'INode, du MTime, ou de la taille du fichier statique contenant les directives SSI.

Directive <Files>

Description: | Contient des directives qui s'appliquent aux fichiers précisés
Syntaxe: | <Files nom fichier> ... </Files>
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

La directive <Files> limite la portée des directives qu'elle contient aux fichiers précisés. Elle est comparable aux directives <Directory> et <Location>. Elle doit se terminer par une balise </Files>. Les directives contenues dans cette section s'appliqueront à tout objet dont le nom de base (la dernière partie du nom de fichier) correspond au fichier spécifié. Les sections <Files> sont traitées selon l'ordre dans lequel elles apparaissent dans le fichier de configuration, après les sections <Directory> et la lecture des fichiers .htaccess, mais avant les sections <Location>. Notez que les sections <Files> peuvent être imbriquées dans les sections <Directory> afin de restreindre la portion du système de fichiers à laquelle ces dernières vont s'appliquer.

L'argument filename peut contenir un nom de fichier ou une chaîne de caractères avec caractères génériques, où ? remplace un caractère, et * toute chaîne de caractères.

<Files "cat.html">
    # Insérer ici des directives qui s'appliquent au fichier cat.html
</Files>

<Files "?at.*">
    # Les directives insérées ici s'appliqueront aux fichiers
    # cat.html, bat.html, hat.php, et ainsi de suite.
</Files>

On peut aussi utiliser les Expressions rationnelles en ajoutant la caractère ~. Par exemple :

<Files ~ "\.(gif|jpe?g|png)$">
    #...
</Files>

correspondrait à la plupart des formats graphiques de l'Internet. Il est cependant préférable d'utiliser la directive <FilesMatch>.

Notez qu'à la différence des sections <Directory> et <Location>, les sections <Files> peuvent être utilisées dans les fichiers .htaccess. Ceci permet aux utilisateurs de contrôler l'accès à leurs propres ressources, fichier par fichier.

Voir aussi

  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour une explication de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête

Directive <FilesMatch>

Description: | Contient des directives qui s'appliquent à des fichiers spécifiés sous la forme d'expressions rationnelles
Syntaxe: | <FilesMatch expression rationnelle> ... </FilesMatch>
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

La section <FilesMatch> limite la portée des directives qu'elle contient aux fichiers spécifiés, tout comme le ferait une section <Files>. Mais elle accepte aussi les expressions rationnelles. Par exemple :

<FilesMatch ".+\.(gif|jpe?g|png)$">
    # ...
</FilesMatch>

correspondrait à la plupart des formats graphiques de l'Internet.

Les caractères .+ au début de l'expression rationnelle permettent de s'assurer que les fichiers de nom .png, ou .gif, par exemple, ne seront pas pris en compte.

A partir de la version 2.4.8, les groupes nommés et les références arrières sont extraits et enregistrés dans l'environnement avec leur nom en majuscules et préfixé par "MATCH_". Ceci permet de référencer des URLs dans des expressions ou au sein de modules comme mod_rewrite. Pour éviter toute confusion, les références arrières numérotées (non nommées) sont ignorées. Vous devez utiliser à la place des groupes nommés.

<FilesMatch "^(?<sitename>[^/]+)">
    require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</FilesMatch>

Voir aussi

  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour une explication de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête

Directive ForceType

Description: | Force le type de médium spécifié dans le champ d'en-tête HTTP Content-Type pour les fichiers correspondants
Syntaxe: | ForceType type médium|None
Contexte: | répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core

Lorsqu'elle est placée dans un fichier .htaccess ou une section <Directory>, <Location>, ou <Files>, cette directive force l'identification du type MIME des fichiers spécifiés à la valeur de l'argument type médium. Par exemple, si vous possédez un répertoire ne contenant que des fichiers GIF, et si vous ne voulez pas leur ajouter l'extension .gif, vous pouvez utiliser :

ForceType image/gif

Notez que cette directive l'emporte sur d'autres associations de type de médium indirectes définies dans mime.types ou via la directive AddType.

Vous pouvez aussi annuler toute définition plus générale de ForceType en affectant la valeur None à l'argument type médium :

# force le type MIME de tous les fichiers à image/gif:
<Location "/images">
  ForceType image/gif
</Location>

# mais utilise les méthodes classiques d'attribution du type MIME
# dans le sous-répertoire suivant :
<Location "/images/mixed">
  ForceType None
</Location>

A la base, cette directive écrase le type de contenu généré pour les fichiers statiques servis à partir du sytème de fichiers. Pour les ressources autres que les fichiers statiques pour lesquels le générateur de réponse spécifie en général un type de contenu, cette directive est ignorée.

Note

Lorsque des directives explicites comme SetHandler ou module="mod_mime">AddHandler ne s'appliquent pas à la requête courante, le nom du gestionnaire interne normalement défini par ces directives correspondra alors au type de contenu spécifié par cette directive. Il s'agit d'un comportement historique que certains modules tiers, comme mod_php, peuvent interpréter comme un type de contenu artificiel ne servant qu'à indiquer le module qui doit prendre en compte la requête considérée. Dans la mesure du possible, il est conseillé d'éviter les configurations qui comportent de tels types artificiels en utilisant les directives SetHandler ou AddHandler.

Directive GprofDir

Description: | Répertoire dans lequel écrire les données de profiling gmon.out.
Syntaxe: | GprofDir /tmp/gprof/|/tmp/gprof/%
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Lorsque le serveur a été compilé avec le support du profiling gprof, la directive GprofDir permet de spécifier dans quel répertoire les fichiers gmon.out doivent être écrits lorsque le processus s'arrête. Si l'argument se termine par un caractère pourcentage ('%'), des sous-répertoires sont créés pour chaque identifiant de processus.

Cette directive ne fonctionne actuellement qu'avec le MPM prefork.

Directive HostnameLookups

Description: | Active la recherche DNS sur les adresses IP des clients
Syntaxe: | HostnameLookups On|Off|Double
Défaut: | HostnameLookups Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core

Cette directive active la recherche DNS afin de pouvoir journaliser les nom d'hôtes (et les passer aux programmes CGI et aux inclusions SSI via la variable REMOTE_HOST). La valeur Double déclenche une double recherche DNS inverse. En d'autres termes, une fois la recherche inverse effectuée, on lance une recherche directe sur le résultat de cette dernière. Au moins une des adresses IP fournies par la recherche directe doit correspondre à l'adresse originale (ce que l'on nomme PARANOID dans la terminologie "tcpwrappers").

Quelle que soit la configuration, lorsqu'on utilise mod_authz_host pour contrôler l'accès en fonction du nom d'hôte, une double recherche DNS inverse est effectuée, sécurité oblige. Notez cependant que le résultat de cette double recherche n'est en général pas accessible, à moins que vous n'ayez spécifié HostnameLookups Double. Par exemple, si vous n'avez spécifié que HostnameLookups On, et si une requête concerne un objet protégé par des restrictions en fonction du nom d'hôte, quel que soit le résultat de la double recherche inverse, les programmes CGI ne recevront que le résultat de la recherche inverse simple dans la variable REMOTE_HOST.

La valeur par défaut est Off afin de préserver le traffic réseau des sites pour lesquels la recherche inverse n'est pas vraiment nécessaire. Cette valeur par défaut est aussi bénéfique pour les utilisateurs finaux car il n'ont ainsi pas à subir de temps d'attente supplémentaires dus aux recherches DNS. Les sites fortement chargés devraient laisser cette directive à Off, car les recherches DNS peuvent prendre des temps très longs. Vous pouvez éventuellement utiliser hors ligne l'utilitaire logresolve, compilé par défaut dans le sous-répertoire bin de votre répertoire d'installation, afin de déterminer les noms d'hôtes associés aux adresses IP journalisées.

Enfin, si vous avez des directives Require à base de nom, une recherche de nom d'hôte sera effectuée quelle que soit la définition de la directive HostnameLookups.

Directive HttpProtocolOptions

Description: | Modifie les contraintes sur les messages des requêtes HTTP
Syntaxe: | HttpProtocolOptions [Strict|Unsafe] [RegisteredMethods|LenientMethods] [Allow0.9|Require1.0]
Défaut: | HttpProtocolOptions Strict LenientMethods Allow0.9
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core
Compatibilité: | Disponible à partir des versions 2.2.32 et 2.4.24 du serveur HTTP Apache

Cette directive permet de modifier les règles qui s'appliquent à la ligne de requête HTTP (RFC 7230 §3.1.1) et aux champs des en-têtes des requêtes HTTP (RFC 7230 §3.2), qui s'appliquent maintenant par défaut ou en utilisant l'option Strict. L'option Unsafe a été ajoutée pour pouvoir restaurer les anciens comportements nécessaires aux anciens modules et applications et aux agents utilisateurs personnalisés considérés comme obsolètes.

Ces règles s'appliquant avant le traitement de la requête, elles doivent, pour être prises en compte, être définies au niveau global ou dans la première section par défaut du serveur virtuel qui correspond à la requête considérée, par interface IP/port et non par nom.

Cette directive accepte trois paramètres issus de la liste suivante, ceux qui ne sont pas spécifiés prenant leur valeur par défaut :

Strict|Unsafe

Avant l'introduction de cette directive, les interpréteurs de requêtes du serveur HTTP Apache toléraient un grand nombre de formats en entrée qui n'étaient pas forcément conformes au protocole. RFC 7230 §9.4 Request Splitting et §9.5 Response Smuggling ne rappellent que deux des risques potentiels induits par des requêtes non conformes, alors que RFC 7230 §3.5 signale les risques encourus par l'acceptation de blancs non conformes dans les lignes de requête. Avec l'introduction de cette directive, toutes les règles de grammaire de la spécification doivent être respectées dans le mode d'opérations par défaut Strict.

Risques de sécurité liés au mode Unsafe

Il est fortement déconseillé aux utilisateurs d'utiliser le mode d'opération Unsafe, ou UnsafeWhitespace, en particulier pour les déploiements de serveurs ouverts sur l'extérieur et/ou accessibles au public. Si un moniteur défectueux ou autre logiciel spécialisé ne s'exécutant que sur un intranet nécessite une interface, les utilisateurs ne doivent utiliser les options de type UnSafe qu'en cas de nécessité et uniquement au sein d'un serveur virtuel bien spécifique et sur un réseau privé.

Exemple de requête provoquant l'envoi d'un message HTTP 400 en mode Strict

# Missing CRLF
GET / HTTP/1.0\n\n

Utilitaires en ligne de commande et CRLF

Il peut s'avérer nécessaire de forcer certains utilitaires à utiliser CRLF ; si ce n'est pas le cas, httpd reverra une réponse HTTP 400 comme dans le cas précédent. Par exemple, le client OpenSSL s_client doit utiliser le paramètre -crlf pour fonctionner correctement.

Pour détecter des problèmes tels que l'absence de CRLF, vous pouvez utiliser la directive DumpIOInput qui permet de décortiquer les requêtes HTTP.

RegisteredMethods|LenientMethods

La section de la RFC 7231 §4.1 "Request Methods" "Overview" indique que les serveurs doivent renvoyer un message d'erreur lorsque la ligne de requête comporte une méthode non supportée. C'est déjà le cas lorsque l'option LenientMethods est utilisée, mais les administrateurs ont la possibilité de limiter les méthodes utilisées via l'option RegisteredMethods en enregistrant toute méthode non standard via la directive RegisterHttpMethod, en particulier si l'option Unsafe est utilisée.

Compatibilité avec le mandat direct

L'option RegisteredMethods ne doit pas être utilisée pour les serveurs mandataires car ces derniers ne connaissent pas les méthodes supportées par les serveurs originaux.

Exemple de requête provoquant l'envoi d'un message HTTP 501 en mode LenientMethods

# Méthode HTTP inconnue
WOW / HTTP/1.0\r\n\r\n

# Méthode HTTP spécifiée en minuscules
get / HTTP/1.0\r\n\r\n

Allow0.9|Require1.0

La section de la RFC 2616 §19.6 "Compatibility With Previous Versions" encouragait les serveurs HTTP à supporter les anciennes requêtes HTTP/0.9. La RFC 7230 va cependant à son encontre via sa préconisation "Le souhait de supporter les requêtes HTTP/0.9 a été supprimé" et y adjoint des commentaires dans RFC 7230 Appendix A. A ce titre, l'option Require1.0 permet à l'utilisateur d'inhiber le comportement induit par l'option par défaut Allow0.9.

Exemple de requête provoquant l'envoi d'un message HTTP 400 en mode Require1.0

# Version HTTP non supportée
GET /\r\n\r\n

La consultation des messages enregistrés dans le journal ErrorLog, configuré via la directive LogLevel avec un niveau info, pourra vous aider à identifier de telles requêtes non conformes ainsi que leur provenance. Les utilisateurs devront accorder une attention particulière aux messages d'erreur de type 400 dans le journal access pour détecter les requêtes apparemment valides mais rejetées.

Directive <If>

Description: | Contient des directives qui ne s'appliquent que si une condition est satisfaite au cours du traitement d'une requête
Syntaxe: | <If expression> ... </If>
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core
Compatibilité: | Les conditions imbriquées sont supportées à partir de la version 2.4.26 du serveur HTTP Apache

La directive <If> évalue une expression à la volée, et applique les directives qu'elle contient si et seulement si l'expression renvoie la valeur "vrai". Par exemple :

<If "-z req('Host')">

serait satisfaite pour les requêtes HTTP/1.0 sans en-tête Host:. Les expressions peuvent contenir différents opérateurs de type shell pour la comparaison de chaînes (==, !=, <, ...), la comparaison d'entiers (-eq, -ne, ...), ou à usages divers (-n, -z, -f, ...). Les expressions rationnelles sont aussi supportées,

<If "%{QUERY_STRING} =~ /(delete|commit)=.*?elem/">

ainsi que les comparaison de modèles de type shell et de nombreuses autres opérations. Ces opérations peuvent être effectuées sur les en-têtes de requêtes (req), les variables d'environnement (env), et un grand nombre d'autres propriétés. La documentation complète est disponible dans Les expressions dans le serveur HTTP Apache.

Cette section de configuration ne peut contenir que des directives qui supportent le contexte de répertoire.

Certain variables, such as CONTENT_TYPE and other response headers, are set after <If> conditions have already been evaluated, and so will not be available to use in this directive.

Voir aussi

  • Les expressions dans le serveur HTTP Apache, pour une référence complète et d'autres exemples.
  • <ElseIf>
  • <Else>
  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour une explication de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête. Les directives <If>, <ElseIf>, et <Else> s'appliquent en dernier.

Directive <IfDefine>

Description: | Contient des directives qui ne s'appliqueront que si un test retourne "vrai" au démarrage du serveur
Syntaxe: | <IfDefine [!]paramètre> ... </IfDefine>
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

La section <IfDefine test>...</IfDefine> permet de conférer un caractère conditionnel à un ensemble de directives. Les directives situées à l'intérieur d'une section <IfDefine> ne s'appliquent que si test est vrai. Si test est faux, tout ce qui se trouve entre les balises de début et de fin est ignoré.

test peut se présenter sous deux formes :

  • nom paramètre
  • !nom paramètre

Dans le premier cas, les directives situées entre les balises de début et de fin ne s'appliqueront que si le paramètre nommé nom paramètre est défini. Le second format inverse le test, et dans ce cas, les directives ne s'appliqueront que si nom paramètre n'est pas défini.

L'argument nom paramètre est une définition qui peut être effectuée par la ligne de commande httpd via le paramètre -Dparamètre au démarrage du serveur, ou via la directive Define.

Les sections <IfDefine> peuvent être imbriquées, ce qui permet d'implémenter un test multi-paramètres simple. Exemple :

httpd -DReverseProxy -DUseCache -DMemCache ...

<IfDefine ReverseProxy>
  LoadModule proxy_module   modules/mod_proxy.so
  LoadModule proxy_http_module   modules/mod_proxy_http.so
  <IfDefine UseCache>
    LoadModule cache_module   modules/mod_cache.so
    <IfDefine MemCache>
      LoadModule mem_cache_module   modules/mod_mem_cache.so
    </IfDefine>
    <IfDefine !MemCache>
      LoadModule cache_disk_module   modules/mod_cache_disk.so
    </IfDefine>
  </IfDefine>
</IfDefine>

Directive <IfModule>

Description: | Contient des directives qui ne s'appliquent qu'en fonction de la présence ou de l'absence d'un module spécifique
Syntaxe: | <IfModule [!]fichier module|identificateur module> ... </IfModule>
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core
Compatibilité: | Les identificateurs de modules sont disponibles dans les versions 2.1 et supérieures.

La section <IfModule test>...</IfModule> permet de conférer à des directives un caractère conditionnel basé sur la présence d'un module spécifique. Les directives situées dans une section <IfModule> ne s'appliquent que si test est vrai. Si test est faux, tout ce qui se trouve entre les balises de début et de fin est ignoré.

test peut se présenter sous deux formes :

  • module
  • !module

Dans le premier cas, les directives situées entre les balises de début et de fin ne s'appliquent que si le module module est présent -- soit compilé avec le binaire Apache httpd, soit chargé dynamiquement via la directive LoadModule. Le second format inverse le test, et dans ce cas, les directives ne s'appliquent que si module n'est pas présent.

L'argument module peut contenir soit l'identificateur du module, soit le nom du fichier source du module. Par exemple, rewrite_module est un identificateur et mod_rewrite.c le nom du fichier source correspondant. Si un module comporte plusieurs fichiers sources, utilisez le nom du fichier qui contient la chaîne de caractères STANDARD20_MODULE_STUFF.

Les sections <IfModule> peuvent être imbriquées, ce qui permet d'implémenter des tests multi-modules simples.

Cette section ne doit être utilisée que si votre fichier de configuration ne fonctionne qu'en fonction de la présence ou de l'absence d'un module spécifique. D'une manière générale, il n'est pas nécessaire de placer les directives à l'intérieur de sections <IfModule>.

Directive Include

Description: | Inclut d'autres fichiers de configuration dans un des fichiers de configuration du serveur
Syntaxe: | Include chemin-fichier|chemin-répertoire|wildcard
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core
Compatibilité: | Utilisation des caractères génériques dans la partie chemin depuis la version 2.3.6

Cette directive permet l'inclusion d'autres fichiers de configuration dans un des fichiers de configuration du serveur.

On peut utiliser des caractères génériques de style Shell (fnmatch()) aussi bien dans la partie nom de fichier du chemin que dans la partie répertoires pour inclure plusieurs fichiers en une seule fois, selon leur ordre alphabétique. De plus, si la directive Include pointe vers un répertoire, Apache httpd inclura tous les fichiers de ce répertoire et de tous ces sous-répertoires. L'inclusion de répertoires entiers est cependant déconseillée, car il est fréquent d'oublier des fichiers temporaires dans un répertoire, ce qui causerait une erreur httpd en cas d'inclusion. Pour inclure des fichiers qui correspondent à un certain modèle, comme *.conf par exemple, nous vous recommandons d'utiliser plutôt la syntaxe avec caractères génériques comme ci-dessous.

La directive Include échouera avec un code d'erreur si une expression contenant des caractères génériques ne correspond à aucun fichier. Pour ignorer les expressions contenant des caractères génériques ne correspondant à aucun fichier, utilisez la directive IncludeOptional.

Le chemin fichier spécifié peut être soit un chemin absolu, soit un chemin relatif au répertoire défini par la directive ServerRoot.

Exemples :

Include /usr/local/apache2/conf/ssl.conf
Include /usr/local/apache2/conf/vhosts/*.conf

ou encore, avec des chemins relatifs au répertoire défini par la directive ServerRoot :

Include conf/ssl.conf
Include conf/vhosts/*.conf

On peut aussi insérer des caractères génériques dans la partie répertoires du chemin. Dans l'exemple suivant, la directive échouera si aucun sous-répertoire de conf/vhosts ne contient au moins un fichier *.conf :

Include conf/vhosts/*/*.conf

Par contre, dans l'exemple suivant, la directive sera simplement ignorée si aucun sous-répertoire de conf/vhosts ne contient au moins un fichier *.conf :

IncludeOptional conf/vhosts/*/*.conf

Voir aussi

  • IncludeOptional
  • apachectl

Directive IncludeOptional

Description: | Inclusion de fichiers dans le fichier de configuration
Syntaxe: | IncludeOptional file-path|directory-path|wildcard
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core
Compatibilité: | Disponible à partir de la version 2.3.6 du serveur HTTP Apache. Après la version 2.4.30, les chemins de fichiers non existants et ne comportant pas de caractères génériques ne génèrent plus d'erreurs de syntaxe

Cette directive permet d'inclure des fichiers dans les fichiers de configuration du serveur. Elle fonctionne de manière identique à la directive Include, mais au lieu de générer une erreur, elle sera ignorée silensieusement si malgré l'utilisation de caractères génériques, le chemin de fichier ou de répertoire spécifié n'existe pas dans le système de fichiers.

Voir aussi

  • Include
  • apachectl

Directive KeepAlive

Description: | Active les connexions HTTP persistantes
Syntaxe: | KeepAlive On|Off
Défaut: | KeepAlive On
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

L'extension Keep-Alive de HTTP/1.0 et l'implémentation des connexions persistantes dans HTTP/1.1 ont rendu possibles des sessions HTTP de longue durée, ce qui permet de transmettre plusieurs requêtes via la même connexion TCP. Dans certains cas, le gain en rapidité pour des documents comportant de nombreuses images peut atteindre 50%. Pour activer les connexions persistantes, définissez KeepAlive On.

Pour les clients HTTP/1.0, les connexions persistantes ne seront mises en oeuvre que si elles ont été spécialement demandées par un client. De plus, une connexion persistante avec un client HTTP/1.0 ne peut être utilisée que si la taille du contenu est connue d'avance. Ceci implique que les contenus dynamiques comme les sorties CGI, les pages SSI, et les listings de répertoires générés par le serveur n'utiliseront en général pas les connexions persistantes avec les clients HTTP/1.0. Avec les clients HTTP/1.1, les connexions persistantes sont utilisées par défaut, sauf instructions contraires. Si le client le demande, le transfert par tronçons de taille fixe (chunked encoding) sera utilisé afin de transmettre un contenu de longueur inconnue via une connexion persistante.

Lorsqu'un client utilise une connexion persistante, elle comptera pour une seule requête pour la directive MaxConnectionsPerChild, quel que soit le nombre de requêtes transmises via cette connexion.

Voir aussi

  • MaxKeepAliveRequests

Directive KeepAliveTimeout

Description: | Durée pendant laquelle le serveur va attendre une requête avant de fermer une connexion persistante
Syntaxe: | KeepAliveTimeout nombre[ms]
Défaut: | KeepAliveTimeout 5
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Le nombre de secondes pendant lesquelles Apache httpd va attendre une requête avant de fermer la connexion. Le délai peut être défini en millisecondes en suffixant sa valeur par ms. La valeur du délai spécifiée par la directive Timeout s'applique dès qu'une requête a été reçue.

Donner une valeur trop élévée à KeepAliveTimeout peut induire des problèmes de performances sur les serveurs fortement chargés. Plus le délai est élévé, plus nombreux seront les processus serveur en attente de requêtes de la part de clients inactifs.

Si la directive KeepAliveTimeout n'est pas définie pour un serveur virtuel à base de nom, c'est la valeur de la paire adresse IP/port du serveur virtuel qui correspond le mieux qui sera utilisée.

Directive <Limit>

Description: | Limite les contrôles d'accès que la section contient à certaines méthodes HTTP
Syntaxe: | <Limit méthode [méthode] ... > ... </Limit>
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig, Limit
Statut: | Core
Module: | core

Les contrôles d'accès s'appliquent normalement à toutes les méthodes d'accès, et c'est en général le comportement souhaité. Dans le cas général, les directives de contrôle d'accès n'ont pas à être placées dans une section <Limit>.

La directive <Limit> a pour but de limiter les effets des contrôles d'accès aux méthodes HTTP spécifiées. Pour toutes les autres méthodes, les restrictions d'accès contenues dans la section <Limit> n'auront aucun effet. L'exemple suivant n'applique les contrôles d'accès qu'aux méthodes POST, PUT, et DELETE, en laissant les autres méthodes sans protection :

<Limit POST PUT DELETE>
  Require valid-user
</Limit>

La liste des noms de méthodes peut contenir une ou plusieurs valeurs parmi les suivantes : GET, POST, PUT, DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, et UNLOCK. Le nom de méthode est sensible à la casse. Si la valeur GET est présente, les requêtes HEAD seront aussi concernées. La méthode TRACE ne peut pas être limitée (voir la directive TraceEnable).

Une section <LimitExcept> doit toujours être préférée à une section <Limit> pour la restriction d'accès, car une section <LimitExcept> fournit une protection contre les méthodes arbitraires.

Les directives <Limit> et <LimitExcept> peuvent être imbriquées. Dans ce cas, pour chaque niveau des directives <Limit> ou <LimitExcept>, ces dernières doivent restreindre l'accès pour les méthodes auxquelles les contrôles d'accès s'appliquent.

Lorsqu'on utilise les directives <Limit> ou <LimitExcept> avec la directive Require, la première directive Require dont la condition est satisfaite autorise la requête, sans tenir compte de la présence d'autres directives Require.

Par exemple, avec la configuration suivante, tous les utilisateurs seront autorisés à effectuer des requêtes POST, et la directive Require group editors sera ignorée dans tous les cas :

<LimitExcept GET>
  Require valid-user
</LimitExcept>
<Limit POST>
  Require group editors
</Limit>

Directive <LimitExcept>

Description: | Applique les contrôles d'accès à toutes les méthodes HTTP, sauf celles qui sont spécifiées
Syntaxe: | <LimitExcept méthode [méthode] ... > ... </LimitExcept>
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig, Limit
Statut: | Core
Module: | core

<LimitExcept> et </LimitExcept> permettent de regrouper des directives de contrôle d'accès qui s'appliqueront à toutes les méthodes d'accès HTTP qui ne font pas partie de la liste des arguments ; en d'autres termes, elles ont un comportement opposé à celui de la section <Limit>, et on peut les utiliser pour contrôler aussi bien les méthodes standards que les méthodes non standards ou non reconnues. Voir la documentation de la section <Limit> pour plus de détails.

Par exemple :

<LimitExcept POST GET>
  Require valid-user
</LimitExcept>

Directive LimitInternalRecursion

Description: | Détermine le nombre maximal de redirections internes et de sous-requêtes imbriquées
Syntaxe: | LimitInternalRecursion nombre [nombre]
Défaut: | LimitInternalRecursion 10
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Une redirection interne survient, par exemple, quand on utilise la directive Action qui redirige en interne la requête d'origine vers un script CGI. Une sous-requête est le mécanisme qu'utilise Apache httpd pour déterminer ce qui se passerait pour un URI s'il faisait l'objet d'une requête. Par exemple, mod_dir utilise les sous-requêtes pour rechercher les fichiers listés dans la directive DirectoryIndex.

La directive LimitInternalRecursion permet d'éviter un crash du serveur dû à un bouclage infini de redirections internes ou de sous-requêtes. De tels bouclages sont dus en général à des erreurs de configuration.

La directive accepte, comme arguments, deux limites qui sont évaluées à chaque requête. Le premier nombre est le nombre maximum de redirections internes qui peuvent se succéder. Le second nombre détermine la profondeur d'imbrication maximum des sous-requêtes. Si vous ne spécifiez qu'un seul nombre, il sera affecté aux deux limites.

LimitInternalRecursion 5

Directive LimitRequestBody

Description: | limite la taille maximale du corps de la requête HTTP envoyée par le client
Syntaxe: | LimitRequestBody octets
Défaut: | LimitRequestBody 0
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

Cette directive spécifie la taille maximale autorisée pour le corps d'une requête ; la valeur de l'argument octets va de 0 (pour une taille illimitée), à 2147483647 (2Go). Voir la note ci-dessous pour la limite d'applicabilité aux requêtes mandatées.

La directive LimitRequestBody permet de définir une limite pour la taille maximale autorisée du corps d'une requête HTTP en tenant compte du contexte dans lequel la directive a été placée (c'est à dire au niveau du serveur, d'un répertoire, d'un fichier ou d'une localisation). Si la requête du client dépasse cette limite, le serveur répondra par un message d'erreur et ne traitera pas la requête. La taille du corps d'une requête normale va varier de manière importante en fonction de la nature de la ressource et des méthodes autorisées pour cette dernière. Les scripts CGI utilisent souvent le corps du message pour extraire les informations d'un formulaire. Les implémentations de la méthode PUT nécessitent une valeur au moins aussi élevée que la taille maximale des représentations que le serveur désire accepter pour cette ressource.

L'administrateur du serveur peut utiliser cette directive pour contrôler plus efficacement les comportements anormaux des requêtes des clients, ce qui lui permettra de prévenir certaines formes d'attaques par déni de service.

Si par exemple, vous autorisez le chargement de fichiers vers une localisation particulière, et souhaitez limiter la taille des fichiers chargés à 100Ko, vous pouvez utiliser la directive suivante :

LimitRequestBody 102400

Pour une description détaillée de la manière dont cette directive est interprétée par les requêtes mandatées, voir la documentation du module mod_proxy.

Directive LimitRequestFields

Description: | Limite le nombre de champs d'en-tête autorisés dans une requête HTTP
Syntaxe: | LimitRequestFields nombre
Défaut: | LimitRequestFields 100
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

nombre est un entier de 0 (nombre de champs illimité) à 32767. La valeur par défaut est définie à la compilation par la constante DEFAULT_LIMIT_REQUEST_FIELDS (100 selon la distribution).

La directive LimitRequestFields permet à l'administrateur du serveur de modifier le nombre maximum de champs d'en-tête autorisés dans une requête HTTP. Pour un serveur, cette valeur doit être supérieure au nombre de champs qu'une requête client normale peut contenir. Le nombre de champs d'en-tête d'une requête qu'un client utilise dépasse rarement 20, mais ce nombre peut varier selon les implémentations des clients, et souvent en fonction des extensions que les utilisateurs configurent dans leurs navigateurs pour supporter la négociation de contenu détaillée. Les extensions HTTP optionnelles utilisent souvent les champs d'en-tête des requêtes.

L'administrateur du serveur peut utiliser cette directive pour contrôler plus efficacement les comportements anormaux des requêtes des clients, ce qui lui permettra de prévenir certaines formes d'attaques par déni de service. La valeur spécifiée doit être augmentée si les clients standards reçoivent une erreur du serveur indiquant que la requête comportait un nombre d'en-têtes trop important.

Par exemple :

LimitRequestFields 50

Avertissement

Dans le cas des serveurs virtuels à base de noms, la valeur de cette directive est extraite du serveur virtuel par défaut (le premier de la liste) pour la paire adresse IP/port.

Directive LimitRequestFieldSize

Description: | Dédinit la taille maximale autorisée d'un en-tête de requête HTTP
Syntaxe: | LimitRequestFieldSize octets
Défaut: | LimitRequestFieldSize 8190
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Cette directive permet de définir le nombre maximum d'octets autorisés dans un en-tête de requête HTTP.

La directive LimitRequestFieldSize permet à l'administrateur du serveur de définir la taille maximale autorisée d'un en-tête de requête HTTP. Pour un serveur, cette valeur doit être suffisamment grande pour contenir tout en-tête d'une requête client normale. La taille d'un champ d'en-tête de requête normal va varier selon les implémentations des clients, et en fonction des extensions que les utilisateurs configurent dans leurs navigateurs pour supporter la négociation de contenu détaillée. Les en-têtes d'authentification SPNEGO peuvent atteindre une taille de 12392 octets.

>L'administrateur du serveur peut utiliser cette directive pour contrôler plus efficacement les comportements anormaux des requêtes des clients, ce qui lui permettra de prévenir certaines formes d'attaques par déni de service.

Par exemple ::

LimitRequestFieldSize 4094
Dans des conditions normales, la valeur par défaut de cette directive ne doit pas être modifiée.

Avertissement

Dans le cas des serveurs virtuels à base de noms, la valeur de cette directive est extraite du serveur virtuel par défaut (le premier de la liste) pour lequel la paire adresse IP/port correspond le mieux.

Directive LimitRequestLine

Description: | Définit la taille maximale d'une ligne de requête HTTP
Syntaxe: | LimitRequestLine octets
Défaut: | LimitRequestLine 8190
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Cette directive permet de définir la taille maximale autorisée pour une ligne de requête HTTP en octets.

La directive LimitRequestLine permet à l'administrateur du serveur de définir la taille maximale autorisée d'une ligne de requête HTTP client. Comme une requête comporte une méthode HTTP, un URI, et une version de protocole, la directive LimitRequestLine impose une restriction sur la longueur maximale autorisée pour un URI dans une requête au niveau du serveur. Pour un serveur, cette valeur doit être suffisamment grande pour référencer les noms de toutes ses ressources, y compris toutes informations pouvant être ajoutées dans la partie requête d'une méthode GET.

L'administrateur du serveur peut utiliser cette directive pour contrôler plus efficacement les comportements anormaux des requêtes des clients, ce qui lui permettra de prévenir certaines formes d'attaques par déni de service.

Par exemple :

LimitRequestLine 4094
Dans des conditions normales, cette directive doit conserver sa valeur par défaut.

Avertissement

Dans le cas des serveurs virtuels à base de noms, la valeur de cette directive est extraite du serveur virtuel par défaut (le premier de la liste) pour lequel la paire adresse IP/port correspond le mieux.

Directive LimitXMLRequestBody

Description: | Définit la taille maximale du corps d'une requête au format XML
Syntaxe: | LimitXMLRequestBody octets
Défaut: | LimitXMLRequestBody 1000000
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

Taille maximale (en octets) du corps d'une requête au format XML. Une valeur de 0 signifie qu'aucune limite n'est imposée.

Exemple :

LimitXMLRequestBody 0

Directive <Location>

Description: | N'applique les directives contenues qu'aux URLs spécifiées
Syntaxe: | <Location chemin URL|URL> ... </Location>
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive <Location> limite la portée des directives contenues aux URLs définies par l'argument URL. Elle est similaire à la directive <Directory>, et marque le début d'une section qui se termine par une directive </Location>. Les sections <Location> sont traitées selon l'ordre dans lequel elles apparaissent dans le fichier de configuration, mais après les sections <Directory> et la lecture des fichiers .htaccess, et après les sections <Files>.

Les sections <Location> agissent complètement en dehors du système de fichiers. Ceci a de nombreuses conséquences. Parmi les plus importantes, on ne doit pas utiliser les sections <Location> pour contrôler l'accès aux répertoires du système de fichiers. Comme plusieurs URLs peuvent correspondre au même répertoire du système de fichiers, un tel contrôle d'accès pourrait être contourné.

Les directives que contient cette section seront appliquées aux requêtes si la partie chemin de l'URL satisfait à l'un au moins de ces critères :

  • Le chemin spécifié correspond exactement à la partie chemin de l'URL.
  • Le chemin spécifié, qui se termine par un slash, est un préfixe de la partie chemin de l'URL (traité comme une racine du contexte).
  • Le chemin spécifié, si on lui ajoute un slash de fin, est un préfixe de la partie chemin de l'URL (aussi traité comme une racine du contexte).

Dans l'exemple ci-dessous, où aucun slash de fin n'est utilisé, les directives contenues dans la section s'appliqueront à /private1, /private1/ et /private1/file.txt, mais pas à /private1other.

<Location "/private1">
    #  ...
</Location>

De même, dans l'exemple ci-dessous, où l'on utilise un slash de fin, les directives contenues dans la section s'appliqueront à /private2/ et à /private2/file.txt, mais pas à /private2other.

<Location "/private2/">
    # ...
</Location>

Quand utiliser la section <Location>

Vous pouvez utiliser une section <Location> pour appliquer des directives à des contenus situés en dehors du système de fichiers. Pour les contenus situés à l'intérieur du système de fichiers, utilisez plutôt les sections <Directory> et <Files>. <Location "/"> constitue une exception et permet d'appliquer aisément une configuration à l'ensemble du serveur.

Pour toutes les requêtes originales (non mandatées), l'argument URL est un chemin d'URL de la forme /chemin/. Aucun protocole, nom d'hôte, port, ou chaîne de requête ne doivent apparaître. Pour les requêtes mandatées, l'URL spécifiée doit être de la forme protocole://nom_serveur/chemin, et vous devez inclure le préfixe.

L'URL peut contenir des caractères génériques. Dans une chaîne avec caractères génériques, ? correspond à un caractère quelconque, et * à toute chaîne de caractères. Les caractères génériques ne peuvent pas remplacer un / dans le chemin URL.

On peut aussi utiliser les Expressions rationnelles, moyennant l'addition d'un caractère ~. Par exemple :

<Location ~ "/(extra|special)/data">
    #...
</Location>

concernerait les URLs contenant les sous-chaîne /extra/data ou /special/data. La directive <LocationMatch> présente un comportement identique à la version avec expressions rationnelles de la directive <Location>, et son utilisation est préférable à l'utilisation de cette dernière pour la simple raison qu'il est difficile de distinguer ~ de - dans la plupart des fontes.

La directive <Location> s'utilise principalement avec la directive SetHandler. Par exemple, pour activer les requêtes d'état, mais ne les autoriser que depuis des navigateurs appartenant au domaine example.com, vous pouvez utiliser :

<Location "/status">
  SetHandler server-status
  Require host example.com
</Location>

Note à propos du slash (/)

La signification du caractère slash dépend de l'endroit où il se trouve dans l'URL. Les utilisateurs peuvent être habitués à son comportement dans le système de fichiers où plusieurs slashes successifs sont souvent réduits à un slash unique (en d'autres termes, /home///foo est identique à /home/foo). Dans l'espace de nommage des URLs, ce n'est cependant pas toujours le cas. Pour la directive <LocationMatch> et la version avec expressions rationnelles de la directive <Location>, vous devez spécifier explicitement les slashes multiples si telle est votre intention.

Par exemple, <LocationMatch "^/abc"> va correspondre à l'URL /abc mais pas à l'URL //abc. La directive <Location> sans expression rationnelle se comporte de la même manière lorsqu'elle est utilisée pour des requêtes mandatées. Par contre, lorsque la directive <Location> sans expression rationnelle est utilisée pour des requêtes non mandatées, elle fera correspondre implicitement les slashes multiples à des slashes uniques. Par exemple, si vous spécifiez <Location "/abc/def">, une requête de la forme /abc//def correspondra.

Voir aussi

  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour une explication de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête.

Directive <LocationMatch>

Description: | N'applique les directives contenues qu'aux URLs correspondant à une expression rationnelle
Syntaxe: | <LocationMatch regex> ... </LocationMatch>
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive <LocationMatch> limite la portée des directives contenues à l'URL spécifiée, de manière identique à la directive <Location>. Mais son argument permettant de spécifier les URLs concernées est une expression rationnelle au lieu d'une simple chaîne de caractères. Par exemple :

<LocationMatch "/(extra|special)/data">
    # ...
</LocationMatch>

correspondrait à toute URL contenant les sous-chaînes /extra/data ou /special/data.

Si vous recherchez une URL commençant par plutôt que seulement contenant /extra/data, préfixez l'expression rationnelle avec un ^.

<LocationMatch "^/(extra|special)/data">

A partir de la version 2.4.8, les groupes nommés et les références arrières sont extraits et enregistrés dans l'environnement avec leur nom en majuscules et préfixé par "MATCH_". Ceci permet de référencer des URLs dans des expressions ou au sein de modules comme mod_rewrite. Pour éviter toute confusion, les références arrières numérotées (non nommées) sont ignorées. Vous devez utiliser à la place des groupes nommés.

<LocationMatch "^/combined/(?<sitename>[^/]+)">
    require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</LocationMatch>

Voir aussi

  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour une explication de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête.

Directive LogLevel

Description: | Contrôle la verbosité du journal des erreurs
Syntaxe: | LogLevel [module:]niveau [module:niveau] ...
Défaut: | LogLevel warn
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core
Compatibilité: | La configuration du niveau de journalisation par module et par répertoire est disponible depuis la version 2.3.6 du serveur HTTP Apache

La directive LogLevel permet d'ajuster la verbosité des messages enregistrés dans les journaux d'erreur (voir la directive ErrorLog directive). Les niveaux disponibles sont présentés ci-après, par ordre de criticité décroissante :

Niveau | Description | Exemple
emerg | Urgences - le système est inutilisable. | "Child cannot open lock file. Exiting"
alert | Des mesures doivent être prises immédiatement. | "getpwuid: couldn't determine user name from uid"
crit | Conditions critiques. | "socket: Failed to get a socket, exiting child"
error | Erreurs. | "Premature end of script headers"
warn | Avertissements. | "child process 1234 did not exit, sending another SIGHUP"
notice | Evènement important mais normal. | "httpd: caught SIGBUS, attempting to dump core in ..."
info | Informations. | "Server seems busy, (you may need to increase StartServers, or Min/MaxSpareServers)..."
debug | Messages de débogage. | "Opening config file ..."
trace1 | Messages de traces | "proxy: FTP: control connection complete"
trace2 | Messages de traces | "proxy: CONNECT: sending the CONNECT request to the remote proxy"
trace3 | Messages de traces | "openssl: Handshake: start"
trace4 | Messages de traces | "read from buffered SSL brigade, mode 0, 17 bytes"
trace5 | Messages de traces | "map lookup FAILED: map=rewritemap key=keyname"
trace6 | Messages de traces | "cache lookup FAILED, forcing new map lookup"
trace7 | Messages de traces, enregistrement d'une grande quantité de données | "| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"
trace8 | Messages de traces, enregistrement d'une grande quantité de données | "| 0000: 02 23 44 30 13 40 ac 34 df 3d bf 9a 19 49 39 15 |"

Lorsqu'un niveau particulier est spécifié, les messages de tous les autres niveaux de criticité supérieure seront aussi enregistrés. Par exemple, si LogLevel info est spécifié, les messages de niveaux notice et warn seront aussi émis.

Il est recommandé d'utiliser un niveau crit ou inférieur.

Par exemple :

LogLevel notice

Note

Si la journalisation s'effectue directement dans un fichier, les messages de niveau notice ne peuvent pas être supprimés et sont donc toujours journalisés. Cependant, ceci ne s'applique pas lorsque la journalisation s'effectue vers syslog.

Spécifier un niveau sans nom de module va attribuer ce niveau à tous les modules. Spécifier un niveau avec nom de module va attribuer ce niveau à ce module seulement. Il est possible de spécifier un module par le nom de son fichier source ou par son identificateur, avec ou sans le suffixe _module. Les trois spécifications suivantes sont donc équivalentes :

LogLevel info ssl:warn
LogLevel info mod_ssl.c:warn
LogLevel info ssl_module:warn

Il est aussi possible d'attribuer un niveau de journalisation par répertoire :

LogLevel info
<Directory "/usr/local/apache/htdocs/app">
  LogLevel debug
</Directory>
La configuration du niveau de journalisation par répertoire n'affecte que les messages journalisés après l'interprétation de la requête et qui sont associés à cette dernière. Les messages de journalisation associés à la connexion ou au serveur ne sont pas affectés.

Voir aussi

  • ErrorLog
  • ErrorLogFormat
  • Journaux du serveur HTTP Apache

Directive MaxKeepAliveRequests

Description: | Nombre de requêtes permises pour une connexion persistante
Syntaxe: | MaxKeepAliveRequests nombre
Défaut: | MaxKeepAliveRequests 100
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive MaxKeepAliveRequests permet de limiter le nombre de requêtes autorisées par connexion lorsque KeepAlive est à "on". Si sa valeur est 0, le nombre de requêtes autorisées est illimité. Il est recommandé de définir une valeur assez haute pour des performances du serveur maximales.

Par exemple :

MaxKeepAliveRequests 500

Directive MaxRangeOverlaps

Description: | Nombre de chevauchements de segments de données autorisé (par exemple 100-200,150-300) avant le renvoi de la ressource complète
Syntaxe: | MaxRangeOverlaps default | unlimited | none | nombre de chevauchements
Défaut: | MaxRangeOverlaps 20
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core
Compatibilité: | Disponible depuis la version 2.3.15 du serveur HTTP Apache

La directive MaxRangeOverlaps permet de limiter le nombre de chevauchements de segments de données HTTP autorisé par le serveur. Si le nombre de chevauchements de segments demandé est supérieur au nombre maximal autorisé, la ressource sera renvoyée dans son intégralité.

default
Limite le nombre de chevauchements de segments à la valeur par défaut 20 définie à la compilation.
none
Aucun chevauchement de segment n'est autorisé.
unlimited
Le nombre de chevauchements de segments est illimité.
number-of-ranges
Un nombre positif représente le nombre maximal de chevauchements de segments autorisé par le serveur.

Directive MaxRangeReversals

Description: | Nombre d'inversions d'ordre autorisé dans la spécification des segments de données (par exemple 100-200,50-70) avant le renvoi de la ressource complète
Syntaxe: | MaxRangeReversals default | unlimited | none | nombre d'inversions
Défaut: | MaxRangeReversals 20
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core
Compatibilité: | Disponible depuis la version 2.3.15 du serveur HTTP Apache

La directive MaxRangeReversals permet de limiter le nombre d'inversions d'ordre dans la spécification des segments de données HTTP autorisé par le serveur. Si le nombre d'inversions demandé est supérieur au nombre maximal autorisé, la ressource sera renvoyée dans son intégralité.

default
Limite le nombre d'inversions à la valeur par défaut 20 définie à la compilation.
none
Aucune inversion n'est autorisée.
unlimited
Le nombre d'inversions est illimité.
number-of-ranges
Un nombre positif représente le nombre maximal d'inversions autorisé par le serveur.

Directive MaxRanges

Description: | Nombre de segments de données autorisé avant le renvoi de l'intégralité de la ressource
Syntaxe: | MaxRanges default | unlimited | none | nombre de segments
Défaut: | MaxRanges 200
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core
Compatibilité: | Disponible depuis la version 2.3.15 du serveur HTTP Apache

La directive MaxRanges permet de limiter le nombre de segments de données que le serveur va renvoyer au client. Si un nombre de segments plus important est demandé, la ressource sera renvoyée dans son intégralité.

default
Limite le nombre de segments de données à 200 (valeur par défaut définie à la compilation).
none
Les en-têtes Range sont ignorés.
unlimited
Le nombre de segments de données est illimité.
nombre de segments
Un nombre positif représentera la nombre de segments de données maximal que le serveur renverra au client.

Directive MergeTrailers

Description: | Détermine si les données supplémentaires (trailers) sont fusionnées avec les en-têtes
Syntaxe: | MergeTrailers [on|off]
Défaut: | MergeTrailers off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core
Compatibilité: | Disponible à partir de la version 2.4.11 du serveur HTTP Apache

Cette directive permet de contrôler la fusion des données HTTP supplémentaires (trailers) avec la représentation interne des en-têtes. Cette fusion intervient lorsque le corps de la requête a été entièrement reçu, bien longtemps après que la majeure partie du traitement des en-têtes ait une chance de pouvoir examiner ou modifier les en-têtes de la requête.

Cette option a été introduite dans un souci de compatibilité avec les versions antérieures à 2.4.11, où les données supplémentaires étaient systématiquement fusionnées avec les en-têtes de la requête.

Directive Mutex

Description: | Définit les mécanismes de mutex et le repertoire du fichier verrou pour tous les mutex ou seulement les mutex spécifiés
Syntaxe: | Mutex mécanisme [default|nom-mutex] ... [OmitPID]
Défaut: | Mutex default
Contexte: | configuration du serveur
Statut: | Core
Module: | core
Compatibilité: | Disponible depuis la version 2.3.4 du serveur HTTP Apache

La directive Mutex permet de définir le mécanisme de mutex, et éventuellement le répertoire du fichier verrou que les modules et httpd utilisent pour sérialiser l'accès aux ressources. Spécifiez default comme second argument pour modifier la configuration de tous les mutex ; spécifiez un nom de mutex (voir la table ci-dessous) comme second argument pour ne modifier que la configuration de ce mutex.

La directive Mutex est typiquement utilisée dans les situations exceptionnelles suivantes :

  • choix d'un autre mécanisme de mutex lorsque le mécanisme par défaut sélectionné par APR présente un problème de fonctionnement ou de performances.
  • choix d'un autre répertoire utilisé par les mutex à base de fichier lorsque le répertoire par défaut ne supporte pas le verrouillage

Modules supportés

Cette directive ne configure que les mutex qui ont été enregistrés avec le serveur de base via l'API ap_mutex_register(). Tous les modules fournis avec httpd supportent la directive Mutex, mais il n'en sera pas forcément de même pour les modules tiers. Reportez-vous à la documentation du module tiers considéré afin de déterminer le(s) nom(s) de mutex qui pourront être définis si la directive est supportée.

Les mécanismes de mutex disponibles sont les suivants :

  • default | yes

    C'est l'implémentation du verrouillage par défaut, telle qu'elle est définie par APR. On peut afficher l'implémentation du verrouillage par défaut via la commande httpd avec l'option -V.

  • none | no

    Le mutex est désactivé, et cette valeur n'est permise pour un mutex que si le module indique qu'il s'agit d'un choix valide. Consultez la documentation du module pour plus d'informations.

  • posixsem

    Une variante de mutex basée sur un sémaphore Posix.

    Avertissement

    La propriété du sémaphore n'est pas restituée si un thread du processus gérant le mutex provoque une erreur de segmentation, ce qui provoquera un blocage du serveur web.

  • sysvsem

    Une variante de mutex basée sur un sémaphore IPC SystemV.

    Avertissement

    Il peut arriver que les sémaphores SysV soient conservés si le processus se crashe avant que le sémaphore ne soit supprimé.

    Sécurité

    L'API des sémaphores permet les attaques par déni de service par tout programme CGI s'exécutant sous le même uid que le serveur web (autrement dit tous les programmes CGI, à moins que vous n'utilisiez un programme du style suexec ou cgiwrapper).

  • sem

    Sélection de la "meilleure" implémentation des sémaphores disponible ; le choix s'effectue entre les sémaphores posix et IPC SystemV, dans cet ordre.

  • pthread

    Une variante de mutex à base de mutex de thread Posix inter-processus.

    Avertissement

    Sur la plupart des systèmes, si un processus enfant se termine anormalement alors qu'il détenait un mutex qui utilise cette implémentation, le serveur va se bloquer et cesser de répondre aux requêtes. Dans ce cas, un redémarrage manuel est nécessaire pour récupérer le mutex.

    Solaris et Linux constituent des exceptions notables, en ceci qu'ils fournissent un mécanisme qui permet en général de récupérer le mutex après l'arrêt anormal d'un processus enfant qui détenait le mutex.

    Si votre système est compatible POSIX ou implémente la fonction pthread_mutexattr_setrobust_np(), vous devriez pouvoir utiliser l'option pthread sans problème.

  • fcntl:/chemin/vers/mutex

    Une variante de mutex utilisant un fichier verrou physique et la fonction fcntl().

    Avertissement

    Lorsqu'on utilise plusieurs mutex basés sur ce mécanisme dans un environnement multi-processus, multi-thread, des erreurs de blocage (EDEADLK) peuvent être rapportées pour des opérations de mutex valides si la fonction fcntl() ne gère pas les threads, comme sous Solaris.

  • flock:/chemin/vers/mutex

    Méthode similaire à fcntl:/chemin/vers/mutex, mais c'est la fonction flock() qui est utilisée pour gérer le verrouillage par fichier.

  • file:/chemin/vers/mutex

    Sélection de la "meilleure" implémentation de verrouillage par fichier disponible ; le choix s'effectue entre fcntl et flock, dans cet ordre.

La plupart des mécanismes ne sont disponibles que sur les plate-formes où ces dernières et APR les supportent. Les mécanismes qui ne sont pas disponibles sur toutes les plate-formes sont posixsem, sysvsem, sem, pthread, fcntl, flock, et file.

Avec les mécanismes à base de fichier fcntl et flock, le chemin, s'il est fourni, est un répertoire dans lequel le fichier verrou sera créé. Le répertoire par défaut est le répertoire d'exécution de httpd relatif à la directive ServerRoot. Utilisez toujours un système de fichiers local sur disque pour /chemin/vers/mutex et jamais un répertoire se trouvant dans un système de fichiers NFS ou AFS. Le nom de base du fichier se composera du type de mutex, d'une chaîne optionnelle correspondant à l'instance et fournie par le module ; et, sauf si le mot-clé OmitPID a été spécifié, l'identificateur du processus parent httpd sera ajouté afin de rendre le nom du fichier unique, évitant ainsi tout conflit lorsque plusieurs instances d'httpd partagent le même répertoire de verrouillage. Par exemple, si le nom de mutex est mpm-accept, et si le répertoire de verrouillage est /var/httpd/locks, le nom du fichier verrou pour l'instance httpd dont le processus parent a pour identifiant 12345 sera /var/httpd/locks/mpm-accept.12345.

Sécurité

Il est conseillé d'éviter de placer les fichiers mutex dans un répertoire où tout le monde peut écrire comme /var/tmp, car quelqu'un pourrait initier une attaque par déni de service et empêcher le serveur de démarrer en créant un fichier verrou possédant un nom identique à celui que le serveur va tenter de créer.

La table suivante décrit les noms de mutex utilisés par httpd et ses modules associés.

Nom mutex | Module(s) | Ressource protégée
mpm-accept | modules MPM prefork et worker | connexions entrantes, afin d'éviter le problème de l'afflux de requêtes ; pour plus d'informations, voir la documentation Amélioration des performances
authdigest-client | mod_auth_digest | liste de clients en mémoire partagée
authdigest-opaque | mod_auth_digest | compteur en mémoire partagée
ldap-cache | mod_ldap | cache de résultat de recherche LDAP
rewrite-map | mod_rewrite | communication avec des programmes externes d'associations de valeurs, afin d'éviter les interférences d'entrées/sorties entre plusieurs requêtes
ssl-cache | mod_ssl | cache de session SSL
ssl-stapling | mod_ssl | cache de l'étiquetage OCSP ("OCSP stapling")
watchdog-callback | mod_watchdog | fonction de rappel d'un module client particulier

Le mot-clé OmitPID permet d'empêcher l'addition de l'identifiant du processus httpd parent au nom du fichier verrou.

Dans l'exemple suivant, le mécanisme de mutex pour le mutex mpm-accept est modifié pour passer du mécanisme par défaut au mécanisme fcntl, avec le fichier verrou associé créé dans le répertoire /var/httpd/locks. Le mécanisme de mutex par défaut pour tous les autres mutex deviendra sysvsem.

Mutex sysvsem default
Mutex fcntl:/var/httpd/locks mpm-accept

Directive NameVirtualHost

Description: | OBSOLETE : Définit une adresse IP pour les serveurs virtuels à base de nom
Syntaxe: | NameVirtualHost adresse[:port]
Contexte: | configuration du serveur
Statut: | Core
Module: | core

Avant la version 2.3.11, il était nécessaire de définir une directive NameVirtualHost pour indiquer au serveur qu'une paire adresse IP/port particulière pouvait être utilisée comme serveur virtuel à base de nom. Depuis la version 2.3.11, chaque fois qu'une paire adresse IP/port est utilisée dans plusieurs serveurs virtuels, l'hébergement virtuel à base de nom est automatiquement activé pour cette adresse.

Cette directive n'a actuellement plus aucun effet.

Voir aussi

  • Documentation sur les serveurs virtuels

Directive Options

Description: | Définit les fonctionnalités disponibles pour un répertoire particulier
Syntaxe: | Options [+|-]option [[+|-]option] ...
Défaut: | Options FollowSymlinks
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Core
Module: | core
Compatibilité: | Avec la version 2.3.11, la valeur par défaut passe de All à FollowSymlinks

La directive Options permet de définir les fonctionnalités de serveur disponibles pour un répertoire particulier.

option peut être défini à None, auquel cas aucune fonctionnalité spécifique n'est activée, ou comprendre une ou plusieurs des options suivantes :

All
Toutes les options excepté MultiViews.
ExecCGI
L'exécution de scripts CGI à l'aide du module mod_cgi est permise.
FollowSymLinks
Le serveur va suivre les liens symboliques dans le répertoire concerné. Il s'agit de la valeur par défaut.

Bien que le serveur suive les liens symboliques, il ne modifie pas le nom de chemin concerné défini par la section <Directory>.

Les options FollowSymLinks et SymLinksIfOwnerMatch ne fonctionnent que dans les sections <Directory> ou les fichiers .htaccess.

Le fait d'omettre cette option ne doit pas être considéré comme une mesure de sécurité efficace, car il existe toujours une situation de compétition (race condition) entre l'instant où l'on vérifie qu'un chemin n'est pas un lien symbolique, et l'instant où l'on utilise effectivement ce chemin.

Includes
Les inclusions côté serveur (SSI) à l'aide du module mod_include sont autorisées.
IncludesNOEXEC
Les inclusions côté serveur (SSI) sont permises, mais #exec cmd et #exec cgi sont désactivés. L'utilisation de #include virtual pour les scripts CGI est cependant toujours possible depuis des répertoires définis par ScriptAlias.
Indexes
Si une URL requise correspond au répertoire concerné, et si aucun DirectoryIndex (par exemple index.html) n'est défini pour ce répertoire, le module mod_autoindex va renvoyer un listing formaté du répertoire.
MultiViews
Les vues multiples ("multiviews") à contenu négocié à l'aide du module mod_negotiation sont autorisées.

Note

Cette option est ignorée si elle est définie en tout autre endroit qu'une section <Directory>, car mod_negotiation a besoin de ressources réelles pour effectuer ses comparaisons et ses évaluations.

SymLinksIfOwnerMatch
Le serveur ne suivra que les liens symboliques qui renvoient vers un fichier ou un répertoire dont le propriétaire est le même que celui du lien.

Note

Les options FollowSymLinks et SymLinksIfOwnerMatch ne fonctionnent que dans les sections <Directory> ou les fichiers .htaccess.

Le fait d'omettre cette option ne doit pas être considéré comme une mesure de sécurité efficace, car il existe toujours une situation de compétition (race condition) entre l'instant où l'on vérifie qu'un chemin n'est pas un lien symbolique, et l'instant où l'on utilise effectivement ce chemin.

Normalement, si plusieurs directives Options peuvent s'appliquer à un répertoire, c'est la plus spécifique qui est utilisée et les autres sont ignorées ; les options ne sont pas fusionnées (voir comment les sections sont fusionnées). Elles le sont cependant si toutes les options de la directive Options sont précédées d'un symbole + ou -. Toute option précédée d'un + est ajoutée à la liste des options courantes de manière forcée et toute option précédée d'un - est supprimée de la liste des options courantes de la même manière.

Note

Mélanger des Options avec + ou - avec des Options sans + ou - constitue une erreur de syntaxe, et la vérification de la syntaxe au cours du démarrage du serveur fera échouer ce dernier.

Par exemple, sans aucun symbole + et - :

<Directory "/web/docs">
  Options Indexes FollowSymLinks
</Directory>

<Directory "/web/docs/spec">
  Options Includes
</Directory>

ici, seule l'option Includes sera prise en compte pour le répertoire /web/docs/spec. Par contre, si la seconde directive Options utilise les symboles + et - :

<Directory "/web/docs">
  Options Indexes FollowSymLinks
</Directory>

<Directory "/web/docs/spec">
  Options +Includes -Indexes
</Directory>

alors, les options FollowSymLinks et Includes seront prises en compte pour le répertoire /web/docs/spec.

Note

L'utilisation de -IncludesNOEXEC ou -Includes désactive complètement les inclusions côté serveur sans tenir compte des définitions précédentes.

En l'absence de toute définition d'options, la valeur par défaut est FollowSymlinks.

Directive Protocol

Description: | Protocole pour une socket d'écoute
Syntaxe: | Protocol protocole
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core
Compatibilité: | Disponible depuis la version 2.1.5 d'Apache, mais seulement depuis la version 2.3.3 sous Windows.

Cette directive permet de spécifier le protocole utilisé pour une socket d'écoute particulière. Le protocole sert à déterminer quel module doit traiter une requête, et d'appliquer les optimisations spécifiques au protocole via la directive AcceptFilter.

Vous ne devez définir le protocole que si vous travaillez avec des ports non standards ; dans le cas général, le protocole http est associé au port 80 et le protocole https au port 443.

Par exemple, si vous travaillez avec le protocole https sur un port non standard, spécifiez le protocole de manière explicite :

Protocol https

Vous pouvez aussi spécifier le protocole via la directive Listen.

Voir aussi

  • AcceptFilter
  • Listen

Directive Protocols

Description: | Protocoles disponibles pour un serveur virtuel ou non
Syntaxe: | Protocols protocole ...
Défaut: | Protocols http/1.1
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core
Compatibilité: | Disponible à partir de la version 2.4.17 du serveur HTTP Apache.

Cette directive permet de spécifier la liste des protocoles supportés par un serveur virtuel ou non. Cette liste énumère les protocoles qu'un client sera autorisé à négocier avec ce serveur.

Par défaut, seul le protocole http/1.1 est disponible (compatible avec les clients http/1.0 et http/0.9). Par conséquent, vous devez fournir cette liste si vous voulez étendre les protocoles disponibles pour le serveur.

Par exemple, si vous voulez autoriser le protocole HTTP/2 pour un serveur avec TLS, utilisez cette directive comme suit :

Protocols h2 http/1.1

Les protocoles valides sont http/1.1 pour les connexions http et https, h2 pour les connections https et h2c pour les connexions http. D'autres modules peuvent fournir d'autres protocoles.

Spécifier des protocoles non disponibles ou désactivés n'aura aucun effet, et ceux-ci seront simplement ignorés.

Si un serveur virtuel ne possède pas de directive Protocols propre, il hérite des protocoles spécifiés pour le serveur principal. Autrement dit, les directives Protocols définies au niveau d'un serveur virtuel remplacent celles définies au niveau du serveur principal.

Voir aussi

  • ProtocolsHonorOrder

Directive ProtocolsHonorOrder

Description: | Détermine qui du client ou du serveur détermine l'ordre des protocoles au cours de la négociation de la connexion
Syntaxe: | ProtocolsHonorOrder On|Off
Défaut: | ProtocolsHonorOrder On
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core
Compatibilité: | Disponible à partir de la version 2.4.17 du serveur HTTP Apache.

Cette directive permet de définir si le serveur doit tenir compte de l'ordre des protocoles définis par la directive Protocols.

Si cette directive est définie à Off, l'ordre de la liste des protocoles fournie par le client l'emporte sur l'ordre défini dans la configuration du serveur.

Si la directive ProtocolsHonorOrder est définie à on (valeur par défaut), il n'est pas tenu compte de l'ordre de la liste des protocoles fournie par le client, et seul l'ordre de la liste des protocles définie au niveau du serveur influera la négociation du protocole.

Voir aussi

  • Protocols

Directive QualifyRedirectURL

Description: | Vérifie si la variable d'environnement REDIRECT_URL est pleinement qualifiée
Syntaxe: | QualifyRedirectURL ON|OFF
Défaut: | QualifyRedirectURL OFF
Contexte: | configuration du serveur, serveur virtuel, répertoire
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | Directive supportée à partir de la version 2.4.18 du serveur HTTP Apache. Jusqu'à la version 2.4.17, le serveur se comportait comme si la directive QualifyRedirectURL était définie à ON.

Cette directive permet de s'assurer que le serveur vérifiera que la variable d'environnement REDIRECT_URL est bien pleinement qualifiée. Par défaut, cette variable contient l'URL textuellement demandée par le client, par exemple "/index.html". Avec QualifyRedirectURL ON, la même requête affectera à la variable REDIRECT_URL une valeur du style "http://www.example.com/index.html".

Même si cette directive n'est pas définie, lorsqu'une requête est soumise avec une URL pleinement qualifiée, la variable REDIRECT_URL contiendra quand-même une URL pleinement qualifiée.

Directive RegisterHttpMethod

Description: | Enregistrement de méthodes HTTP non standards
Syntaxe: | RegisterHttpMethod méthode [méthode [...]]
Contexte: | configuration du serveur
Statut: | Core
Module: | core

Cette directive permet d'enregistrer des méthodes HTTP supplémentaires. Ceci s'avérera nécessaire si l'on doit utiliser des méthodes non standards avec des directives qui acceptent des noms de méthodes en paramètres, ou pour permettre l'utilisation de méthodes particulières non standards en passant par un serveur mandataire ou au sein de scripts CGI, et ceci alors que le serveur a été configuré pour ne transmettre que des méthodes reconnues aux modules.

Voir aussi

  • HTTPProtocolOptions
  • AllowMethods

Directive RLimitCPU

Description: | Limite le temps CPU alloué aux processus initiés par les processus enfants d'Apache httpd
Syntaxe: | RLimitCPU secondes|max [secondes|max]
Défaut: | Non défini ; utilise les valeurs par défaut du système d'exploitation
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

Prend 1 ou 2 paramètres. Le premier definit la limite de consommation de ressources pour tous les processus, et le second la consommation de ressources maximale. Les deux paramètres peuvent contenir soit un nombre, soit max pour indiquer au serveur que la limite de consommation correspond à la valeur maximale autorisée par la configuration du système d'exploitation. Pour augmenter la consommation maximale de ressources, le serveur doit s'exécuter en tant que root, ou se trouver dans sa phase de démarrage.

Cette directive s'applique aux processus initiés par les processus enfants d'Apache httpd qui traitent les requêtes, et non aux processus enfants eux-mêmes. Sont concernés les scripts CGI et les commandes exec des SSI, mais en aucun cas les processus initiés par le processus parent d'Apache httpd comme les journalisations redirigées vers un programme.

Les limites de ressources CPU sont exprimées en secondes par processus.

Voir aussi

  • RLimitMEM
  • RLimitNPROC

Directive RLimitMEM

Description: | Limite la mémoire allouée aux processus initiés par les processus enfants d'Apache httpd
Syntaxe: | RLimitMEM octets|max [octets|max]
Défaut: | Non défini ; utilise les valeurs par défaut du système d'exploitation
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

Prend 1 ou 2 paramètres. Le premier definit la limite de consommation de ressources pour tous les processus, et le second la consommation de ressources maximale. Les deux paramètres peuvent contenir soit un nombre, soit max pour indiquer au serveur que la limite de consommation correspond à la valeur maximale autorisée par la configuration du système d'exploitation. Pour augmenter la consommation maximale de ressources, le serveur doit s'exécuter en tant que root, ou se trouver dans sa phase de démarrage.

Cette directive s'applique aux processus initiés par les processus enfants d'Apache httpd qui traitent les requêtes, et non aux processus enfants eux-mêmes. Sont concernés les scripts CGI et les commandes exec des SSI, mais en aucun cas les processus initiés par le processus parent d'Apache httpd comme les journalisations redirigées vers un programme.

Les limites de ressources mémoire sont exprimées en octets par processus.

Voir aussi

  • RLimitCPU
  • RLimitNPROC

Directive RLimitNPROC

Description: | Limite le nombre de processus qui peuvent être initiés par les processus initiés par les processus enfants d'Apache httpd
Syntaxe: | RLimitNPROC nombre|max [nombre|max]
Défaut: | Unset; uses operating system defaults
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

Prend 1 ou 2 paramètres. Le premier definit la limite de consommation de ressources pour tous les processus, et le second la consommation de ressources maximale. Les deux paramètres peuvent contenir soit un nombre, soit max pour indiquer au serveur que la limite de consommation correspond à la valeur maximale autorisée par la configuration du système d'exploitation. Pour augmenter la consommation maximale de ressources, le serveur doit s'exécuter en tant que root, ou se trouver dans sa phase de démarrage.

Cette directive s'applique aux processus initiés par les processus enfants d'Apache httpd qui traitent les requêtes, et non aux processus enfants eux-mêmes. Sont concernés les scripts CGI et les commandes exec des SSI, mais en aucun cas les processus initiés par le processus parent d'Apache httpd comme les journalisations redirigées vers un programme.

Les limites des processus contrôlent le nombre de processus par utilisateur.

Note

Si les processus CGI s'exécutent sous le même utilisateur que celui du serveur web, cette directive va limiter le nombre de processus que le serveur pourra lui-même créer. La présence de messages cannot fork dans le journal des erreurs indiquera que la limite est atteinte.

Voir aussi

  • RLimitMEM
  • RLimitCPU

Directive ScriptInterpreterSource

Description: | Permet de localiser l'interpréteur des scripts CGI
Syntaxe: | ScriptInterpreterSource Registry|Registry-Strict|Script
Défaut: | ScriptInterpreterSource Script
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | Win32 seulement.

Cette directive permet de contrôler la méthode qu'utilise Apache httpd pour trouver l'interpréteur destiné à exécuter les scripts CGI. La définition par défaut est Script : ceci indique à Apache httpd qu'il doit utiliser l'interpréteur précisé dans la ligne shebang du script (la première ligne, commençant par #!). Sur les systèmes Win32, cette ligne ressemble souvent à ceci :

#!C:/Perl/bin/perl.exe

ou simplement, dans le cas où perl est dans le PATH :

#!perl

Avec ScriptInterpreterSource Registry, Windows va effectuer une recherche dans l'arborescence HKEY_CLASSES_ROOT de la base de registre avec comme mot-clé l'extension du fichier contenant le script (par exemple .pl). C'est la commande définie par la sous-clé de registre Shell\ExecCGI\Command ou, si elle n'existe pas, la sous-clé Shell\Open\Command qui est utilisée pour ouvrir le fichier du script. Si ces clés de registre ne sont pas trouvées, Apache httpd utilise la méthode de l'option Script.

Sécurité

Soyez prudent si vous utilisez ScriptInterpreterSource Registry avec des répertoires faisant l'objet d'un ScriptAlias, car Apache httpd va essayer d'exécuter tous les fichiers contenus dans celui-ci. L'option Registry peut causer des appels de programmes non voulus sur des fichiers non destinés à être exécutés. Par exemple, la commande par défaut open sur les fichiers .htm sur la plupart des systèmes Windows va lancer Microsoft Internet Explorer ; ainsi, toute requête HTTP pour un fichier .htm situé dans le répertoire des scripts va lancer le navigateur en arrière-plan sur le serveur, ce qui a toutes les chances de crasher votre système dans les minutes qui suivent.

L'option Registry-Strict, apparue avec la version 2.0 du serveur HTTP Apache, agit de manière identique à Registry, mais n'utilise que la sous-clé Shell\ExecCGI\Command. La présence de la clé ExecCGI n'étant pas systématique, Elle doit être définie manuellement dans le registre Windows et évite ainsi tout appel de programme accidentel sur votre système.

Directive SeeRequestTail

Description: | Détermine si mod_status affiche les 63 premiers caractères d'une requête ou les 63 derniers, en supposant que la requête elle-même possède plus de 63 caractères.
Syntaxe: | SeeRequestTail On|Off
Défaut: | SeeRequestTail Off
Contexte: | configuration du serveur
Statut: | Core
Module: | core
Compatibilité: | Disponible depuis la version 2.2.7 d'Apache httpd.

Avec ExtendedStatus On, mod_status affiche la véritable requête en cours de traitement. Pour des raisons historiques, seuls 63 caractères de la requête sont réellement stockés à des fins d'affichage. Cette directive permet de déterminer si ce sont les 63 premiers caractères qui seront stockés (c'est le comportement par défaut), ou si ce sont les 63 derniers. Ceci ne s'applique bien entendu que si la taille de la requête est de 64 caractères ou plus.

Si Apache httpd traite la requête GET /disque1/stockage/apache/htdocs/images/rep-images1/nourriture/pommes.jpg HTTP/1.1 , l'affichage de la requête par mod_status se présentera comme suit :

Off (défaut) | GET /disque1/stockage/apache/htdocs/images/rep-images1/nourritu
On | apache/htdocs/images/rep-images1/nourriture/pommes.jpg HTTP/1.1

Directive ServerAdmin

Description: | L'adresse électronique que le serveur inclut dans les messages d'erreur envoyés au client
Syntaxe: | ServerAdmin adresse électronique|URL
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive ServerAdmin permet de définir l'adresse de contact que le serveur va inclure dans tout message d'erreur qu'il envoie au client. Si le programme httpd ne reconnait pas l'argument fourni comme une URL, il suppose que c'est une adresse électronique, et lui ajoute le préfixe mailto: dans les cibles des hyperliens. Il est cependant recommandé d'utiliser exclusivement une adresse électronique, car de nombreux scripts CGI considèrent ceci comme implicite. Si vous utilisez une URL, elle doit pointer vers un autre serveur que vous contrôlez. Dans le cas contraire, les utilisateurs seraient dans l'impossibilité de vous contacter en cas de problème.

Il peut s'avérer utile de définir une adresse dédiée à l'administration du serveur, par exemple :

ServerAdmin www-admin@foo.example.com

car les utilisateurs ne mentionnent pas systématiquement le serveur dont ils parlent !

Directive ServerAlias

Description: | Autres noms d'un serveur utilisables pour atteindre des serveurs virtuels à base de nom
Syntaxe: | ServerAlias nom serveur [nom serveur] ...
Contexte: | serveur virtuel
Statut: | Core
Module: | core

La directive ServerAlias permet de définir les noms alternatifs d'un serveur utilisables pour atteindre des serveurs virtuels à base de nom. La directive ServerAlias peut contenir des caractères génériques, si nécessaire.

<VirtualHost *:80>
  ServerName server.example.com
  ServerAlias server server2.example.com server2
  ServerAlias *.example.com
  UseCanonicalName Off
  # ...
</VirtualHost>

La recherche du serveur virtuel à base de nom correspondant au plus près à la requête s'effectue selon l'ordre d'apparition des directives <virtualhost> dans le fichier de configuration. Le premier serveur virtuel dont le ServerName ou le ServerAlias correspond est choisi, sans priorité particulière si le nom contient des caractères génériques (que ce soit pour ServerName ou ServerAlias).

Tous les noms spécifiés au sein d'une section <VirtualHost> sont traités comme un ServerAlias (sans caractères génériques).

Voir aussi

  • UseCanonicalName
  • Documentation sur les serveurs virtuels du serveur HTTP Apache

Directive ServerName

Description: | Nom d'hôte et port que le serveur utilise pour s'authentifier lui-même
Syntaxe: | ServerName [protocole://]nom-de-domaine|adresse-ip[:port]
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive ServerName permet de définir les protocole, nom d'hôte et port d'une requête que le serveur utilise pour s'authentifier lui-même.

La directive ServerName permet (éventuellement en conjonction avec la directive ServerAlias) d'identifier de manière unique un serveur virtuel, lorsqu'elle est utilisée dans un contexte de serveurs virtuels à base de noms.

Cette directive est aussi utilisée lors de la création d'URLs de redirection relatives quand la directive UseCanonicalName est définie à une valeur autre que la valeur par défaut.

Par exemple, si le nom de la machine hébergeant le serveur web est simple.example.com, la machine possède l'alias DNS www.example.com, et si vous voulez que le serveur web s'identifie avec cet alias, vous devez utilisez la définition suivante :

ServerName www.example.com

La directive ServerName peut apparaître à toutes les étapes de la définition du serveur. Toute occurrence annule cependant la précédente (pour ce serveur).

Si la directive ServerName n'est pas définie, le serveur tente de déterminer le nom d'hôte visible du point de vue du client en demandant tout d'abord au système d'exploitation le nom d'hôte système, et en cas d'échec, en effectuant une recherche DNS inverse sur une adresse IP présente sur le système.

Si la directive ServerName ne précise pas de port, le serveur utilisera celui de la requête entrante. Il est recommandé de spécifier un nom d'hôte et un port spécifiques à l'aide de la directive ServerName pour une fiabilité optimale et à titre préventif.

Si vous définissez des serveurs virtuels à base de nom, une directive ServerName située à l'intérieur d'une section <VirtualHost> spécifiera quel nom d'hôte doit apparaître dans l'en-tête de requête Host: pour pouvoir atteindre ce serveur virtuel.

Parfois, le serveur s'exécute en amont d'un dispositif qui implémente SSL, comme un mandataire inverse, un répartiteur de charge ou un boîtier dédié SSL. Dans ce cas, spécifiez le protocole https:// et le port auquel les clients se connectent dans la directive ServerName, afin de s'assurer que le serveur génère correctement ses URLs d'auto-identification.

Voir la description des directives UseCanonicalName et UseCanonicalPhysicalPort pour les définitions qui permettent de déterminer si les URLs auto-identifiantes (par exemple via le module mod_dir) vont faire référence au port spécifié, ou au port indiqué dans la requête du client.

Si la valeur de la directive ServerName ne peut pas être résolue en adresse IP, le démarrage du serveur provoquera un avertissement. httpd va alors utiliser le résultat de la commande système hostname pour déterminer le nom du serveur, ce qui ne correspondra pratiquement jamais au nom de serveur que vous souhaitez réellement.

httpd: Could not reliably determine the server's fully qualified domain name, using rocinante.local for ServerName

Voir aussi

  • Problèmes concernant le DNS et le serveur HTTP Apache
  • Documentation sur les serveurs virtuels du serveur HTTP Apache
  • UseCanonicalName
  • UseCanonicalPhysicalPort
  • ServerAlias

Directive ServerPath

Description: | Nom de chemin d'URL hérité pour un serveur virtuel à base de nom accédé par un navigateur incompatible
Syntaxe: | ServerPath chemin d'URL
Contexte: | serveur virtuel
Statut: | Core
Module: | core

La directive ServerPath permet de définir le nom de chemin d'URL hérité d'un hôte, à utiliser avec les serveurs virtuels à base de nom.

Voir aussi

  • Documentation sur les serveurs virtuels du serveur HTTP Apache

Directive ServerRoot

Description: | Racine du répertoire d'installation du serveur
Syntaxe: | ServerRoot chemin de répertoire
Défaut: | ServerRoot /usr/local/apache
Contexte: | configuration du serveur
Statut: | Core
Module: | core

La directive ServerRoot permet de définir le répertoire dans lequel le serveur est installé. En particulier, il contiendra les sous-répertoires conf/ et logs/. Les chemins relatifs indiqués dans les autres directives (comme Include ou LoadModule) seront définis par rapport à ce répertoire.

ServerRoot "/home/httpd"

La valeur par défaut de ServerRoot peut être modifiée via l'argument --prefix de la commande configure, et de nombreuses distributions tierces du serveur proposent une valeur différente de celles listées ci-dessus.

Voir aussi

  • the -d options de httpd
  • les conseils à propos de sécurité pour des informations sur la manière de définir correctement les permissions sur le répertoire indiqué par la directive ServerRoot

Directive ServerSignature

Description: | Définit un pied de page pour les documents générés par le serveur
Syntaxe: | ServerSignature On|Off|EMail
Défaut: | ServerSignature Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Core
Module: | core

La directive ServerSignature permet de définir une ligne de pied de page fixe pour les documents générés par le serveur (messages d'erreur, listings de répertoires ftp de mod_proxy, sorties de mod_info, etc...). Dans le cas d'une chaîne de mandataires, l'utilisateur n'a souvent aucun moyen de déterminer lequel des mandataires chaînés a généré un message d'erreur, et c'est une des raisons pour lesquelles on peut être amené à ajouter un tel pied de page.

La valeur par défaut Off supprime la ligne de pied de page (et est ainsi compatible avec le comportement des versions 1.2 et antérieures d'Apache). la valeur On ajoute simplement une ligne contenant le numéro de version du serveur ainsi que le nom du serveur virtuel issu de la directive ServerName, alors que la valeur EMail ajoute en plus une référence "mailto:" à l'administrateur du document référencé issu la directive ServerAdmin.

Après la version 2.0.44, les détails à propos du numéro de version du serveur sont contrôlés à l'aide de la directive ServerTokens.

Voir aussi

  • ServerTokens

Directive ServerTokens

Description: | Configure l'en-tête Server de la réponse HTTP
Syntaxe: | ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full
Défaut: | ServerTokens Full
Contexte: | configuration du serveur
Statut: | Core
Module: | core

Cette directive permet de contrôler le contenu de l'en-tête Server inclus dans la réponse envoyée au client : cet en-tête peut contenir le type de système d'exploitation du serveur, ainsi que des informations à propos des modules compilés avec le serveur.

ServerTokens Full (ou non spécifié)
Le serveur envoie par exemple : Server: Apache/2.4.2 (Unix) PHP/4.2.2 MyMod/1.2
ServerTokens Prod[uctOnly]
Le serveur renvoie (par exemple): Server: Apache
ServerTokens Major
Le serveur renvoie (par exemple): Server: Apache/2
ServerTokens Minor
Le serveur renvoie (par exemple): Server: Apache/2.4
ServerTokens Min[imal]
Le serveur renvoie (par exemple): Server: Apache/2.4.2
ServerTokens OS
Le serveur renvoie (par exemple): Server: Apache/2.4.2 (Unix)

Cette définition s'applique à l'ensemble du serveur et ne peut être activée ou désactivée pour tel ou tel serveur virtuel.

Dans les versions postérieures à 2.0.44, cette directive contrôle aussi les informations fournies par la directive ServerSignature.

Définir ServerTokens à une valeur inférieure à minimal n'est pas recommandé car le débogage des problèmes interopérationnels n'en sera alors que plus difficile. Notez aussi que la désactivation de l'en-tête Server: n'améliore en rien la sécurité de votre serveur ; le concept de "sécurité par l'obscurité" est un mythe et conduit à une mauvaise perception de ce qu'est la sécurité.

Voir aussi

  • ServerSignature

Directive SetHandler

Description: | Force le traitement des fichiers spécifiés par un gestionnaire particulier
Syntaxe: | SetHandler handler-name|none|expression
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core
Compatibilité: | L'argument expression est disponible à partir de la version 2.4.19 su serveur HTTP Apache

Lorsqu'elle se situe à l'intérieur d'un fichier .htaccess, ou d'une section <Directory> ou <Location>, cette directive force le traitement de tous les fichiers spécifiés par le gestionnaire défini par l'argument nom gestionnaire. Par exemple, dans le cas d'un répertoire dont vous voulez interpréter le contenu comme des fichiers de règles d'images cliquables, sans tenir compte des extensions, vous pouvez ajouter la ligne suivante dans un fichier .htaccess de ce répertoire :

SetHandler imap-file

Autre exemple : si vous voulez que le serveur affiche un compte-rendu d'état chaque fois qu'une URL du type http://nom serveur/status est appelée, vous pouvez ajouter ceci dans httpd.conf :

<Location "/status">
  SetHandler server-status
</Location>

Vous pouvez aussi utiliser cette directive pour associer un gestionnaire à des fichiers possèdant une extension de nom de fichier particulière. Par exemple :

<FilesMatch "\.php$">
    SetHandler application/x-httpd-php
</FilesMatch>

Pour référencer des variables spécifiques à une requête, y compris les références arrières vers des expressions rationnelles nommées, vous pouvez utiliser des expressions ayant pour valeur une chaîne :

<LocationMatch ^/app/(?<sub>[^/]+)/>
     SetHandler "proxy:unix:/var/run/app_%{env:MATCH_sub}.sock|fcgi://localhost:8080"
</LocationMatch>

Vous pouvez écraser la définition antérieure d'une directive SetHandler en utilisant la valeur None.

Note

Comme SetHandler l'emporte sur la définition des gestionnaires par défaut, le comportement habituel consistant à traiter les URLs se terminant par un slash (/) comme des répertoires ou des fichiers index est désactivé.

Voir aussi

  • AddHandler

Directive SetInputFilter

Description: | Définit les filtres par lesquels vont passer les requêtes client et les données POST
Syntaxe: | SetInputFilter filtre[;filtre...]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core

La directive SetInputFilter permet de définir le ou les filtres par lesquels vont passer les requêtes client et les données POST au moment où le serveur les reçoit. Cette définition vient en ajout à tout autre filtre défini en quelqu'endroit que ce soit, y compris via la directive AddInputFilter.

Si la directive comporte plusieurs filtres, ils doivent être séparés par des points-virgules, et spécifiés selon l'ordre dans lequel vous souhaitez les voir agir sur les contenus.

Voir aussi

  • documentation des Filtres

Directive SetOutputFilter

Description: | Définit les filtres par lesquels vont passer les réponses du serveur
Syntaxe: | SetOutputFilter filtre[;filtre...]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Core
Module: | core

La directive SetOutputFilter permet de définir les filtres par lesquels vont passer les réponses du serveur avant d'être envoyées au client. Cette définition vient en ajout à tout autre filtre défini en quelqu'endroit que ce soit, y compris via la directive AddOutputFilter.

Par exemple, la configuration suivante va traiter tous les fichiers du répertoire /www/data/ comme des inclusions côté serveur (SSI) :

<Directory "/www/data/">
  SetOutputFilter INCLUDES
</Directory>

Si la directive comporte plusieurs filtres, ils doivent être séparés par des points-virgules, et spécifiés selon l'ordre dans lequel vous souhaitez les voir agir sur les contenus.

Voir aussi

  • Filters documentation

Directive TimeOut

Description: | Temps pendant lequel le serveur va attendre certains évènements avant de considérer qu'une requête a échoué
Syntaxe: | TimeOut secondes
Défaut: | TimeOut 60
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

La directive TimeOut permet de définir le temps maximum pendant lequel Apache httpd va attendre des entrées/sorties selon les circonstances :

  • Lors de la lecture de données en provenance du client, le temps maximum jusqu'à l'arrivée d'un paquet TCP si le tampon est vide.

    Pour les données initiales d'une nouvelle connexion, et tant qu'une directive AcceptFilter n'aura pas transmis cette nouvelle connexion au serveur, cette directive n'aura aucun effet.

  • Lors de l'écriture de données destinées au client, le temps maximum jusqu'à l'arrivée de l'accusé-réception d'un paquet si le tampon d'envoi est plein.
  • Avec mod_cgi et mod_cgid, le temps d'attente maximum pour un bloc individuel en sortie d'un script CGI.
  • Avec mod_ext_filter, le temps d'attente maximum des sorties d'un processus de filtrage.
  • Avec mod_proxy, la valeur du délai par défaut si ProxyTimeout n'est pas défini.

Directive TraceEnable

Description: | Détermine le comportement des requêtes TRACE
Syntaxe: | TraceEnable [on|off|extended]
Défaut: | TraceEnable on
Contexte: | configuration du serveur, serveur virtuel
Statut: | Core
Module: | core

Cette directive l'emporte sur le comportement de TRACE pour le noyau du serveur et mod_proxy. La définition par défaut TraceEnable on permet des requêtes TRACE selon la RFC 2616, qui interdit d'ajouter tout corps à la requête. La définition TraceEnable off indique au noyau du serveur et à mod_proxy de retourner un code d'erreur 405 (Méthode non autorisée) au client.

En fait, et à des fins de test et de diagnostic seulement, on peut autoriser l'ajout d'un corps de requête à l'aide de la définition non standard TraceEnable extended. Le noyau du serveur (dans le cas d'un serveur d'origine) va limiter la taille du corps de requête à 64Kb (plus 8Kb pour les en-têtes de fractionnement si Transfer-Encoding: chunked est utilisé). Le noyau du serveur va reproduire l'ensemble des en-têtes, y compris les en-têtes de fractionnement avec le corps de la réponse. Dans le cas d'un serveur mandataire, la taille du corps de requête n'est pas limitée à 64Kb.

Note

Bien que certains prétendent le contraire, activer la méthode TRACE ne constitue pas un problème de sécurité dans Apache httpd. La méthode TRACE est définie par la spécification HTTP/1.1 et les différentes implémentations sont censées la supporter.

Directive UnDefine

Description: | Invalide la définition d'une variable
Syntaxe: | UnDefine nom-variable
Contexte: | configuration du serveur
Statut: | Core
Module: | core

Annule l'effet d'une directive Define ou d'un argument -D de httpd en invalidant l'existence de la variable correspondante.

On peut utiliser cette directive pour inverser l'effet d'une section <IfDefine> sans avoir à modifier les arguments -D dans les scripts de démarrage.

Si cette directive est définie au sein d'un bloc VirtualHost, les changements qu'elle induit sont visibles de toute directive ultérieure, au delà de tout bloc VirtualHost.

Voir aussi

  • Define
  • IfDefine

Directive UseCanonicalName

Description: | Définit la manière dont le serveur détermine son propre nom et son port
Syntaxe: | UseCanonicalName On|Off|DNS
Défaut: | UseCanonicalName Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core

Dans de nombreuses situations, Apache httpd doit construire une URL auto-identifiante -- c'est à dire une URL qui fait référence au serveur lui-même. Avec UseCanonicalName On, Apache httpd va utiliser le nom d'hôte et le port spécifiés par la directive ServerName pour construire le nom canonique du serveur. Ce nom est utilisé dans toutes les URLs auto-identifiantes, et affecté aux variables SERVER_NAME et SERVER_PORT dans les programmes CGI.

Avec UseCanonicalName Off, Apache httpd va construire ses URLs auto-identifiantes à l'aide du nom d'hôte et du port fournis par le client, si ce dernier en a fourni un (dans la négative, Apache utilisera le nom canonique, de la même manière que ci-dessus). Ces valeurs sont les mêmes que celles qui sont utilisées pour implémenter les serveurs virtuels à base de nom, et sont disponibles avec les mêmes clients. De même, les variables CGI SERVER_NAME et SERVER_PORT seront affectées des valeurs fournies par le client.

Cette directive peut s'avérer utile, par exemple, sur un serveur intranet auquel les utilisateurs se connectent en utilisant des noms courts tels que www. Si les utilisateurs tapent un nom court suivi d'une URL qui fait référence à un répertoire, comme http://www/splat, sans le slash terminal, vous remarquerez qu'Apache httpd va les rediriger vers http://www.example.com/splat/. Si vous avez activé l'authentification, ceci va obliger l'utilisateur à s'authentifier deux fois (une première fois pour www et une seconde fois pour www.example.com -- voir la foire aux questions sur ce sujet pour plus d'informations). Par contre, si UseCanonicalName est définie à Off, Apache httpd redirigera l'utilisateur vers http://www/splat/.

Pour l'hébergement virtuel en masse à base d'adresse IP, on utilise une troisième option, UseCanonicalName DNS, pour supporter les clients anciens qui ne fournissent pas d'en-tête Host:. Apache httpd effectue alors une recherche DNS inverse sur l'adresse IP du serveur auquel le client s'est connecté afin de construire ses URLs auto-identifiantes.

Avertissement

Les programmes CGI risquent d'être perturbés par cette option s'ils tiennent compte de la variable SERVER_NAME. Le client est pratiquement libre de fournir la valeur qu'il veut comme nom d'hôte. Mais si le programme CGI n'utilise SERVER_NAME que pour construire des URLs auto-identifiantes, il ne devrait pas y avoir de problème.

Voir aussi

  • UseCanonicalPhysicalPort
  • ServerName
  • Listen

Directive UseCanonicalPhysicalPort

Description: | Définit la manière dont le serveur détermine son propre port
Syntaxe: | UseCanonicalPhysicalPort On|Off
Défaut: | UseCanonicalPhysicalPort Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Core
Module: | core

Dans de nombreuses situations, Apache httpd doit construire une URL auto-identifiante -- c'est à dire une URL qui fait référence au serveur lui-même. Avec UseCanonicalPhysicalPort On, Apache httpd va fournir le numéro de port physique réel utilisé par la requête en tant que port potentiel, pour construire le port canonique afin que le serveur puisse alimenter la directive UseCanonicalName. Avec UseCanonicalPhysicalPort Off, Apache httpd n'utilisera pas le numéro de port physique réel, mais au contraire se référera aux informations de configuration pour construire un numéro de port valide.

Note

L'ordre dans lequel s'effectue la recherche quand on utilise le port physique est le suivant :

UseCanonicalName On
  1. Port indiqué dans Servername
  2. Port physique
  3. Port par défaut
UseCanonicalName Off | DNS
  1. Port spécifié dans l'en-tête Host:
  2. Port physique
  3. Port spécifié par Servername
  4. Port par défaut

Avec UseCanonicalPhysicalPort Off, on reprend l'ordre ci-dessus en supprimant "Port physique".

Voir aussi

  • UseCanonicalName
  • ServerName
  • Listen

Directive <VirtualHost>

Description: | Contient des directives qui ne s'appliquent qu'à un nom d'hôte spécifique ou à une adresse IP
Syntaxe: | <VirtualHost adresse IP[:port] [adresse IP[:port]] ...> ... </VirtualHost>
Contexte: | configuration du serveur
Statut: | Core
Module: | core

Les balises <VirtualHost> et </VirtualHost> permettent de rassembler un groupe de directives qui ne s'appliquent qu'à un serveur virtuel particulier. Toute directive autorisée dans un contexte de serveur virtuel peut être utilisée. Lorsque le serveur reçoit un requête pour un document hébergé par un serveur virtuel particulier, il applique les directives de configuration rassemblées dans la section <VirtualHost>. adresse IP peut être une des entités suivantes, éventuellement suivies d'un caractère ':' et d'un numéro de port (ou *) :

  • L'adresse IP du serveur virtuel ;
  • Un nom de domaine entièrement qualifié correspondant à l'adresse IP du serveur virtuel (non recommandé) ;
  • Le caractère *, qui agit comme un caractère générique, et correspond à toute adresse IP.
  • La chaîne _default_, dont la signification est identique à celle du caractère *
<VirtualHost 10.1.2.3:80>
  ServerAdmin webmaster@host.example.com
  DocumentRoot "/www/docs/host.example.com"
  ServerName host.example.com
  ErrorLog "logs/host.example.com-error_log"
  TransferLog "logs/host.example.com-access_log"
</VirtualHost>

Les adresses IPv6 doivent être entourées de crochets car dans le cas contraire, un éventuel port optionnel ne pourrait pas être déterminé. Voici un exemple de serveur virtuel avec adresse IPv6 :

<VirtualHost [2001:db8::a00:20ff:fea7:ccea]:80>
  ServerAdmin webmaster@host.example.com
  DocumentRoot "/www/docs/host.example.com"
  ServerName host.example.com
  ErrorLog "logs/host.example.com-error_log"
  TransferLog "logs/host.example.com-access_log"
</VirtualHost>

Chaque serveur virtuel doit correspondre à une adresse IP, un port ou un nom d'hôte spécifique ; dans le premier cas, le serveur doit être configuré pour recevoir les paquets IP de plusieurs adresses (si le serveur n'a qu'une interface réseau, on peut utiliser à cet effet la commande ifconfig alias -- si votre système d'exploitation le permet).

Note

L'utilisation de la directive <VirtualHost> n'affecte en rien les adresses IP sur lesquelles Apache httpd est en écoute. Vous devez vous assurer que les adresses des serveurs virtuels sont bien incluses dans la liste des adresses précisées par la directive Listen.

Tout bloc <VirtualHost> doit comporter une directive ServerName. Dans le cas contraire, le serveur virtuel héritera de la valeur de la directive ServerName issue de la configuration du serveur principal.

A l'arrivée d'une requête, le serveur tente de la faire prendre en compte par la section <VirtualHost> qui correspond le mieux en ne se basant que sur la paire adresse IP/port. Les chaînes sans caractères génériques l'emportent sur celles qui en contiennent. Si aucune correspondance du point de vue de l'adresse IP/port n'est trouvée, c'est la configuration du serveur "principal" qui sera utilisée.

Si plusieurs serveurs virtuels correspondent du point de vue de l'adresse IP/port, le serveur sélectionne celui qui correspond le mieux du point de vue du nom d'hôte de la requête. Si aucune correspondance du point de vue du nom d'hôte n'est trouvée, c'est le premier serveur virtuel dont l'adresse IP/port correspond qui sera utilisé. Par voie de conséquence, le premier serveur virtuel comportant une certaine paire adresse IP/port est le serveur virtuel par défaut pour cette paire adresse IP/port.

Sécurité

Voir le document sur les conseils à propos de sécurité pour une description détaillée des raisons pour lesquelles la sécurité de votre serveur pourrait être compromise, si le répertoire contenant les fichiers journaux est inscriptible par tout autre utilisateur que celui qui démarre le serveur.

Voir aussi

  • Documentation des serveurs virtuels du serveur HTTP Apache
  • Problèmes concernant le DNS et le serveur HTTP Apache
  • Définition des adresses et ports qu'utilise le serveur HTTP Apache
  • Comment fonctionnent les sections <Directory>, <Location> et <Files> pour une explication de la manière dont ces différentes sections se combinent entre elles à la réception d'une requête


mpm_common - Serveur Apache HTTP Version 2.4

Apache MPM : Directives Communes

Description: | Une série de directives implémentées par plusieurs modules multi-processus (MPM)
Statut: | MPM

Directive CoreDumpDirectory

Description: | Le répertoire dans lequel le serveur HTTP Apache va tenter de se positionner avant d'effectuer un vidage mémoire
Syntaxe: | CoreDumpDirectory répertoire
Défaut: | Voir ci-dessous pour le répertoire par défaut
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork

Cette directive permet de définir le répertoire dans lequel Apache httpd va tenter de se positionner avant d'effectuer un vidage mémoire sur disque. Si votre système d'exploitation est configuré pour créer des fichiers de vidage mémoire dans le répertoire de travail des processus qui se sont crashés, CoreDumpDirectory est nécessaire pour définir un répertoire de travail autre que le répertoire par défaut ServerRoot, ce répertoire de travail ne devant pas être accessible en écriture par l'utilisateur sous lequel le serveur s'exécute.

Si vous avez besoin d'un vidage mémoire pour le débogage, vous pouvez utiliser cette directive pour le placer à un endroit différent. Cette directive n'a aucun effet si votre système d'exploitation n'est pas configuré pour créer des fichiers de vidage mémoire dans le répertoire de travail des processus qui se sont crashés.

Vidages mémoire sous Linux

Si Apache httpd est démarré sous l'utilisateur root puis bascule vers un autre utilisateur, le noyau Linux désactive les vidages mémoire, même si le répertoire est accessible en écriture au processus. Apache httpd (versions 2.0.46 et supérieures) réactive les vidages mémoire sous Linux 2.4 et au delà, mais seulement si vous définissez une directive CoreDumpDirectory.

Vidages mémoire sous BSD

Pour activer le vidage mémoire des exécutables suid sur les systèmes de style BSD (comme FreeBSD), définissez kern.sugid_coredump à 1.

Signaux spécifiques

CoreDumpDirectory n'est traité qu'à la reception d'un certain nombre de signaux , SIGFPE, SIGILL, SIGABORT, SIGSEGV, et SIGBUS.

Sur certains systèmes d'exploitation, SIGQUIT provoque aussi un vidage mémoire, mais n'est pas traité par les directives CoreDumpDirectory ou EnableExceptionHook, si bien que la définition du répertoire d'enregistrement du vidage mémoire est entièrement dévolue au système d'exploitation.

Directive EnableExceptionHook

Description: | Active un hook ("point d'accrochage logiciel") qui exécute des gestionnaires d'exception après un crash
Syntaxe: | EnableExceptionHook On|Off
Défaut: | EnableExceptionHook Off
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork

Pour des raisons de sécurité, cette directive n'est disponible que si la compilation du serveur a été configurée avec l'option --enable-exception-hook. Elle permet d'activer un hook ("point d'accrochage logiciel") qui autorise certains modules externes à effectuer un branchement et accomplir telle ou telle action après le crash d'un processus enfant.

Deux modules, mod_whatkilledus et mod_backtrace utilisent ce hook. Veuillez vous référer à la page EnableExceptionHook de Jeff Trawick pour plus d'informations à leur sujet.

Directive GracefulShutdownTimeout

Description: | Spécifie le délai maximum après lequel le serveur va s'arrêter dans le cas d'un arrêt "en douceur"
Syntaxe: | GracefulShutdownTimeout seconds
Défaut: | GracefulShutdownTimeout 0
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork
Compatibilité: | Disponible dans les versions 2.2 et supérieures

La directive GracefulShutdownTimeout permet de spécifier le temps, en secondes, pendant lequel le serveur va continuer à fonctionner après avoir reçu un signal "graceful-stop" ("Arrêt en douceur"), afin de terminer le traitement des connexions en cours.

Définir cette valeur à zéro signifie au serveur d'attendre jusqu'à ce que toutes les requêtes en cours aient été traitées.

Directive Listen

Description: | Les adresses IP et ports sur lesquels le serveur écoute
Syntaxe: | Listen [adresse IP:]numéro port [protocole]
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2
Compatibilité: | L'argument protocole est supporté depuis la version 2.1.5

La directive Listen permet de signifier à Apache httpd de ne se mettre à l'écoute que sur les adresses IP et ports spécifiés ; par défaut, le serveur répond aux requêtes en provenance de toutes les interfaces réseau. La directive Listen est dorénavant requise, et si elle est absente du fichier de configuration, le serveur refusera de démarrer. Ceci constitue un changement par rapport aux versions précédentes d'Apache httpd.

La directive Listen signifie au serveur de n'accepter les requêtes entrantes que vers le port ou le couple adresse-port spécifié. Si seulement un port est spécifié, le serveur se met à l'écoute sur ce port sur toutes les interfaces réseau. Si une adresse IP et un port sont spécifiés, le serveur va se mettre à l'écoute sur ce port sur l'interface réseau correspondant à l'adresse IP.

On peut utiliser autant de directives Listen que nécessaire pour spécifier plusieurs adresses et/ou ports à écouter. Le serveur répondra aux requêtes vers tous les adresses et ports spécifiés.

Par exemple, pour que le serveur accepte les connexions sur les ports 80 et 8000, utilisez :

Listen 80
Listen 8000

Pour que le serveur accepte les connexions sur deux interfaces et ports particuliers, spécifiez :

Listen 192.170.2.1:80
Listen 192.170.2.5:8000

Les adressee IPv6 doivent être entourées de crochets, comme dans l'exemple suivant :

Listen [2001:db8::a00:20ff:fea7:ccea]:80

L'argument optionnel protocole n'est pas nécessaire dans la plupart des configurations. S'il est absent, https est la valeur par défaut pour le port 443 et http l'est pour tous les autres ports. L'argument protocole sert à déterminer quel module doit traiter une requête, et à appliquer des optimisations spécifiques à certains protocoles à l'aide de la directive AcceptFilter.

La spécification d'un protocole n'est nécessaire que si vous utilisez des ports non standards. Par exemple, pour configurer un site en https sur le port 8443 :

Listen 192.170.2.1:8443 https

Condition d'erreur

Plusieurs directives Listen pour les mêmes adresse IP/port vont provoquer l'envoi d'un message d'erreur Address already in use.

Voir aussi

  • Problèmes avec DNS
  • Définition des adresses et ports qu'utilise le serveur HTTP Apache
  • Autre discussion à propos du message d'erreur Address already in use, citant d'autres causes possibles.

Directive ListenBackLog

Description: | Longueur maximale de la liste d'attente des connexions
Syntaxe: | ListenBacklog backlog
Défaut: | ListenBacklog 511
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2

La longueur maximale de la liste d'attente des connexions. En général, aucune modification n'est nécessaire, ni même souhaitable ; cependant, sur certains systèmes, il peut être nécessaire d'en augmenter la valeur en cas d'attaque TCP SYN flood (envoi en masse de requêtes SYN pour saturer le serveur). Voir le paramètre backlog de l'appel système listen(2).

En fait, l'argument backlog sera souvent limité à une valeur inférieure en fonction du système d'exploitation. Notez aussi que de nombreux systèmes d'exploitation ne tiennent pas vraiment compte de la valeur spécifiée pour l'argument backlog, mais s'en inspirent seulement (et choisissent en général une valeur supérieure).

Directive ListenCoresBucketsRatio

Description: | Rapport entre le nombre de coeurs de processeur activés et le nombre de segments d'écoute
Syntaxe: | ListenCoresBucketsRatio ratio
Défaut: | ListenCoresBucketsRatio 0 (disabled)
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork
Compatibilité: | Disponible à partir de la version 2.4.13 du serveur HTTP Apache, avec un noyau supportant l'option de socket SO_REUSEPORT, et distribuant uniformément les nouvelles connexions aux sockets d'écoute des processus (ou threads) qui l'utilisent (par exemple Linux versions 3.9 et ultérieures, mais pas l'implémentation courante de SO_REUSEPORT par les plateformes de type BSD.

Vous pouvez utiliser la directive ListenCoresBucketsRatio pour spécifier un ratio entre le nombre de coeurs de CPU activés et le nombre de segments d'écoute (listeners' buckets) souhaités ; le serveur HTTP Apache va alors créernum_cpu_cores / ratio segments d'écoute, chacun contenant son propre socket d'écoute Listen sur le ou les mêmes ports ; chaque processus enfant sera associé à un seul segment d'écoute (avec une distribution de type round-robin des segments à la création des processus enfants).

Définition du terme coeur de CPU activé ("online")

Sous Linux et BSD, un coeur de CPU peut être activé ou désactivé si Hotplug a été configuré ; la directive ListenCoresBucketsRatio doit donc tenir compte de ce paramètre pour calculer le nombre de segments d'écoute à créer.

La directive ListenCoresBucketsRatio peut améliorer le support de la montée en charge lorsque l'arrivée de nouvelles connexions est/devient un goulot d'étranglement. Le test de cette fonctionnalité avec des machines possédant un nombre de coeurs de CPU important a permit de constater une amélioration des performances significative et des temps de réponse plus courts.

Pour que cette fonctionnalité soit activée, le nombre de coeurs de CPU doit être égal au moins au double du ratio spécifié. Si vous spécifiez la valeur recommandée pour ratio, à savoir 8, le nombre minimum de coeurs de processeurs disponibles sera alors de 16. La valeur optimale de ratio permettant d'obtenir des performances maximales doit être calculée pour chaque système cible, en testant plusieurs valeurs et en observant les résultats.

Cette directive influence le calcul des valeurs limites inférieures de MinSpareThreads et MaxSpareThreads. En effet, pour accepter les connexions de manière optimale, le nombre de processus enfants doit être un multiple du nombre de segments d'écoute.

Cas où plusieurs Listeners ou serveurs HTTP Apache partagent la même adresse IP et port

La définition de l'option SO_REUSEPORT pour les sockets d'écoute permet à plusieurs processus (partageant le même EUID, par exemple root) de se rattacher à la même adresse IP et port, sans obtenir l'erreur de rattachement que le système génère habituellement lorsque ce cas se produit.

Cela signifie aussi que plusieurs instances d'Apache httpd configurées avec le même IP:port et avec une valeur ListenCoresBucketsRatio positive pourraient démarrer sans erreur, et fonctionner ensuite avec une répartition uniforme des connexions entrantes sur ces différentes instances (ce n'est PAS une recommandation et ne constitue pas un usage approprié à tous les cas, mais juste un avertissement sur le fait qu'un véritable problème de rattachement multiple à un IP:port pourrait alors être occulté).

Au sein d'une même instance, Apache httpd vérifie la présence de directives Listen multiples avec la même adresse IP (ou nom d'hôte) et le même port, et refuse de démarrer si c'est le cas, ce qui permet d'éviter la création de segments d'écoute dupliqués qui seraient du coup inutiles et affecteraient les performances. Cependant, il ne peut pas (et n'essaiera pas de le faire) intercepter tous les cas possibles de recouvrement (comme un nom d'hôte correspondant à une adresse IP utilisée quelque part ailleurs).

Directive MaxConnectionsPerChild

Description: | Limite le nombre de connexions qu'un processus enfant va traiter au cours de son fonctionnement
Syntaxe: | MaxConnectionsPerChild number
Défaut: | MaxConnectionsPerChild 0
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2
Compatibilité: | Disponible depuis la version 2.3.9 du serveur HTTP Apache. L'ancien nom MaxRequestsPerChild est encore supporté.

La directive MaxConnectionsPerChild permet de définir le nombre maximum de connexions qu'un processus enfant va pouvoir traiter au cours de son fonctionnement. Lorsqu'il a traité MaxConnectionsPerChild connexions, le processus enfant est arrêté. Si MaxConnectionsPerChild est définie à 0, il n'y a plus aucune limite sur le nombre de connexions que le processus pourra traiter.

Définir MaxConnectionsPerChild à une valeur non nulle limite la quantité de mémoire qu'un processus peut consommer à cause de fuites (accidentelles) de mémoire.

Directive MaxMemFree

Description: | Quantité maximale de mémoire que l'allocateur principal est autorisé à conserver sans appeler free()
Syntaxe: | MaxMemFree KOctets
Défaut: | MaxMemFree 2048
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt, mpm_netware

La directive MaxMemFree permet de définir le nombre maximum de KOctets libres que tout allocateur est autorisé à conserver sans appeler free(). Dans les MPMs threadés, chaque thread possède son propre allocateur. Si elle est définie à 0, la quantité de mémoire libre que peut conserver un allocateur est illimitée.

Directive MaxRequestWorkers

Description: | Nombre maximum de connexions pouvant être traitées simultanément
Syntaxe: | MaxRequestWorkers nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork

La directive MaxRequestWorkers permet de fixer le nombre maximum de requêtes pouvant être traitées simultanément. Si la limite MaxRequestWorkers est atteinte, toute tentative de connexion sera normalement mise dans une file d'attente, et ceci jusqu'à un certain nombre dépendant de la directive ListenBacklog. Lorsqu'un processus enfant se libèrera suite à la fin du traitement d'une requête, la connexion en attente pourra être traitée à son tour.

Pour les serveurs non threadés (c'est à dire utilisant prefork), la directive MaxRequestWorkers définit alors le nombre maximum de processus enfants qui pourront être lancés simultanément pour traiter les requêtes. La valeur par défaut est 256 ; si vous l'augmentez, vous devez aussi augmenter la valeur de la directive ServerLimit.

Pour les serveur threadés et hybrides (utilisant par exemple event ou worker), MaxRequestWorkers définit alors le nombre total de threads qui seront disponibles pour servir les clients. Dans le cas des MPMs hybrides, la valeur par défaut est 16 (directive ServerLimit) multiplié par la valeur 25 (directive ThreadsPerChild). Par conséquent, pour affecter à la directive MaxRequestWorkers une valeur qui requiert plus de 16 processus, vous devez aussi augmenter la valeur de la directive ServerLimit.

Le nom de la directive MaxRequestWorkers était MaxClients avant la version 2.3.13. Cet ancien nom est encore supporté.

Directive MaxSpareThreads

Description: | Nombre maximum de threads inactifs
Syntaxe: | MaxSpareThreads nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, mpm_netware, mpmt_os2

C'est le nombre maximum de threads inactifs. Les MPMs utilisent cette directive de différentes manières.

Pour worker et event, la définition par défaut est MaxSpareThreads 250. Ce MPM gère les threads inactifs au niveau du serveur. Si le serveur possède trop de threads inactifs, des processus enfants seront arrêtés jusqu'à ce que le nombre de threads inactifs repasse en dessous de cette limite. Des processus/threads supplémentaires sont susceptibles d'être créés si ListenCoresBucketsRatio est activée.

Pour mpm_netware, la définition par défaut est MaxSpareThreads 100. Comme ce MPM n'exécute qu'un seul processus, le nombre de processus inactifs est surveillé au niveau du serveur.

mpmt_os2 fonctionne de manière similaire à mpm_netware. Pour mpmt_os2, la valeur par défaut est 10.

Contraintes

La gamme de valeurs pour MaxSpareThreads est limitée. Apache httpd corrigera automatiquement cette valeur selon les règles suivantes :

  • Avec mpm_netware, MaxSpareThreads doit être supérieure à MinSpareThreads.
  • Avec worker et event, MaxSpareThreads doit être supérieure ou égale à la somme de MinSpareThreads et ThreadsPerChild.

Voir aussi

  • MinSpareThreads
  • StartServers
  • MaxSpareServers

Directive MinSpareThreads

Description: | Nombre minimum de threads inactifs qui seront disponibles pour pouvoir traiter les pics de requêtes
Syntaxe: | MinSpareThreads nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, mpm_netware, mpmt_os2

C'est le nombre minimum de threads inactifs pour être en mesure de traiter les pics de requêtes. Les MPMs utilisent cette directive de différentes manières.

Avec worker et event, la définition par défaut est MinSpareThreads 75, et le nombre de threads inactifs est surveillé au niveau du serveur. Si le serveur ne possède pas assez de threads inactifs, des processus enfants sont créés jusqu'à ce que le nombre de threads inactifs repasse au dessus de nombre. Des processus/threads supplémentaires peuvent être créés si ListenCoresBucketsRatio est activée.

Avec mpm_netware, la définition par défaut est MinSpareThreads 10 et, comme ce MPM n'exécute qu'un seul processus, le nombre de threads est surveillé au niveau du serveur.

mpmt_os2 fonctionne de manière similaire à mpm_netware. Pour mpmt_os2, la valeur par défaut est 5.

Voir aussi

  • MaxSpareThreads
  • StartServers
  • MinSpareServers

Directive PidFile

Description: | Ficher dans lequel le serveur enregistre l'identificateur de processus du démon
Syntaxe: | PidFile nom fichier
Défaut: | PidFile logs/httpd.pid
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt, mpmt_os2

La directive PidFile permet de définir le ficher dans lequel le serveur enregistre l'identificateur de processus du démon. Si le chemin du fichier n'est pas absolu, il est considéré comme relatif au chemin défini par la directive ServerRoot.

Exemple

PidFile /var/run/apache.pid

Il est souvent utile de pouvoir envoyer un signal au serveur afin qu'il ferme et ouvre à nouveau ses journaux d'erreur et de transfert, et recharge son fichier de configuration. Pour ce faire, on envoie un signal SIGHUP (kill -1) à l'identificateur de processus enregistré dans le fichier défini par la directive PidFile.

La directive PidFile fait l'objet des mêmes avertissements que ceux concernant le chemin d'enregistrement des fichiers journaux et la sécurité.

Note

Depuis la version 2 du serveur HTTP Apache, nous recommandons de n'utiliser que le script apachectl, ou le script de démarrage fourni avec votre système d'exploitation pour (re)démarrer ou arrêter le serveur.

Directive ReceiveBufferSize

Description: | Taille du tampon TCP en entrée
Syntaxe: | ReceiveBufferSize octets
Défaut: | ReceiveBufferSize 0
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2

Le serveur va fixer la taille du tampon TCP en entrée au nombre d'octets spécifié.

Si la directive est définie à 0, le serveur va utiliser la valeur par défaut adoptée par le système d'exploitation.

Directive ScoreBoardFile

Description: | Chemin du fichier où sont stockées les données concernant la coordination des processus enfants
Syntaxe: | ScoreBoardFile chemin fichier
Défaut: | ScoreBoardFile logs/apache_runtime_status
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt

Le serveur HTTP Apache utilise un tableau de bord pour la communication entre le processus parent et les processus enfants. Pour faciliter cette communication, certaines architectures nécessitent un fichier. En l'absence de cette directive, donc si aucun nom de fichier n'est spécifié, Apache httpd tentera tout d'abord de créer un tableau uniquement en mémoire (en utilisant la mémoire partagée anonyme) ; et si il n'y parvient pas, il tentera de créer un fichier sur disque (en utilisant la mémoire partagée à base de fichier). Si cette directive est utilisée, Apache httpd créera systématiquement un fichier sur disque.

Exemple

ScoreBoardFile /var/run/apache_runtime_status

Une mémoire partagée sous forme de fichier est utile pour les applications tierces qui nécessitent un accès direct au tableau de bord des processus.

Si vous utilisez un ScoreBoardFile, vous pourrez constater une amélioration des performances en le plaçant sur un disque virtuel en RAM. Assurez-vous cependant de tenir compte des mêmes avertissements que ceux concernant le chemin du fichier journal et la sécurité.

Voir aussi

  • Arrêter et redémarrer le serveur HTTP Apache

Directive SendBufferSize

Description: | Taille du tampon TCP en sortie
Syntaxe: | SendBufferSize octets
Défaut: | SendBufferSize 0
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpm_winnt, mpm_netware, mpmt_os2

Définit la taille du tampon TCP en sortie avec le nombre d'octets spécifié. Ceci s'avère souvent très utile pour augmenter les valeurs par défaut standards du passé des systèmes d'exploitation pour les transmissions à grande vitesse et haute densité (c'est à dire de l'ordre de 100ms comme sur les liaisons rapides transcontinentales).

Si la directive est définie à 0, le serveur va utiliser la valeur par défaut adoptée par le système d'exploitation.

L'amélioration des performances des connexions à grande vitesse et à temps de latence élevé, peut nécessiter une intervention au niveau de la configuration de votre système d'exploitation.

Sous certains systèmes d'exploitation, la modification du comportement TCP via une augmentation de la valeur de SendBufferSize risque de ne pas être perceptible, si la directive EnableSendfile n'est pas définie à OFF. Cette interaction ne s'applique qu'aux fichiers statiques.

Directive ServerLimit

Description: | Limite supérieure de la définition du nombre de processus
Syntaxe: | ServerLimit nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork

Avec le MPM prefork, cette directive définit le nombre maximum que l'on peut affecter à la directive MaxRequestWorkers, et ceci pour la durée de vie du processus Apache httpd. Avec les MPMs worker et event, cette directive, en combinaison avec ThreadLimit, définit le nombre maximum que l'on peut affecter à MaxRequestWorkers, et ceci pour la durée de vie du processus Apache httpd. Avec le MPM event, cette directive permet aussi de définir le nombre de processus anciens du serveur pouvant continuer à s'exécuter pour terminer le traitement des connexions ouvertes. Au cours d'un redémarrage, vous pouvez modifier la valeur de la directive MaxRequestWorkers, alors que toute tentative de modification de la valeur de la directive ServerLimit sera ignorée.

Cette directive doit être utilisée avec précaution. Si ServerLimit est définie à une valeur beaucoup plus grande que nécessaire, de la mémoire partagée supplémentaire sera inutilement allouée. Si à la fois ServerLimit et MaxRequestWorkers possèdent des valeurs supérieures à ce que le système peut supporter, ce dernier peut devenir instable ou Apache httpd peut tout simplement refuser de démarrer.

Avec les MPMs prefork et event, n'utilisez cette directive que si vous devez définir MaxRequestWorkers à une valeur supérieure à 256 (valeur par défaut). N'affectez pas à la directive ServerLimit une valeur supérieure à celle que vous avez prévu d'affecter à la directive MaxRequestWorkers.

Avec worker, n'utilisez cette directive que si la définition de vos directives MaxRequestWorkers et ThreadsPerChild nécessitent plus de 16 processus serveurs (valeur par défaut). N'affectez pas à la directive ServerLimit une valeur supérieure au nombre de processus requis pour la définition des directives MaxRequestWorkers et ThreadsPerChild.

Note

Il existe une limite de ServerLimit 20000 codée en dur dans le serveur (200000 pour le MPM prefork). Ceci est censé éviter les effets désastreux que pourrait provoquer une faute de frappe. Pour dépasser cette limite, vous devez modifier la valeur de MAX_SERVER_LIMIT dans le fichier source du mpm et recompiler le serveur.

Voir aussi

  • Arrêter et redémarrer le serveur HTTP Apache

Directive StartServers

Description: | Nombre de processus enfants du serveur créés au démarrage
Syntaxe: | StartServers nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, prefork, mpmt_os2

La directive StartServers permet de définir le nombre de processus enfants du serveur créés au démarrage. Comme le nombre de processus est contrôlé dynamiquement en fonction de la charge (voir MinSpareThreads, MaxSpareThreads, MinSpareServers, MaxSpareServers), il n'est en général pas nécessaire d'ajuster ce paramètre.

La valeur par défaut diffère d'un MPM à l'autre. Pour worker et event, la définition par défaut est StartServers 3 ; la valeur par défaut est 5 pour prefork et 2 pour mpmt_os2.

Directive StartThreads

Description: | Nombre de threads créés au démarrage
Syntaxe: | StartThreads nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | mpm_netware

C'est le nombre de threads créés au démarrage du serveur. Comme le nombre de threads est contrôlé dynamiquement en fonction de la charge (voir MinSpareThreads, MaxSpareThreads, MinSpareServers, MaxSpareServers), il n'est en général pas nécessaire d'ajuster ce paramètre.

Pour mpm_netware, la définition par défaut est StartThreads 50 et, comme il n'y a qu'un processus, il s'agit du nombre total de threads créés au démarrage pour servir les requêtes.

Directive ThreadLimit

Description: | Le nombre de threads maximum que l'on peut définir par processus enfant
Syntaxe: | ThreadLimit nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, mpm_winnt

Cette directive permet de définir le nombre maximum que l'on peut affecter à la directive ThreadsPerChild pour la durée de vie du processus Apache httpd. La directive ThreadsPerChild peut être modifiée au cours d'un redémarrage jusqu'à la valeur de la directive ThreadLimit, mais toute tentative de modification de la directive ThreadLimit au cours d'un redémarrage sera ignorée.

L'utilisation de cette directive doit faire l'objet de précautions particulières. Si ThreadLimit est définie à une valeur très supérieure à la directive ThreadsPerChild, de la mémoire partagée supplémentaire sera inutilement allouée. Si les directives ThreadLimit et ThreadsPerChild sont définies à des valeurs supérieures à ce que le système peut supporter, ce dernier peut devenir instable, ou Apache httpd peut tout simplement refuser de démarrer. Ne définissez pas cette directive à une valeur supérieure à la valeur maximale que vous pensez affecter à la directive ThreadsPerChild pour le processus Apache httpd en cours d'exécution.

La valeur par défaut de la directive ThreadLimit est 1920 avec mpm_winnt, et 64 avec les autres MPMs.

Note

Il existe une limite de ThreadLimit 20000 (ou ThreadLimit 100000 avec event, ThreadLimit 15000 avec mpm_winnt) codée en dur dans le serveur. Ceci est censé éviter les effets désastreux que pourrait provoquer une faute de frappe. Pour dépasser cette limite, vous devez modifier la valeur de MAX_THREAD_LIMIT dans le fichier source du mpm et recompiler le serveur.

Directive ThreadsPerChild

Description: | Nombre de threads créés par chaque processus enfant
Syntaxe: | ThreadsPerChild nombre
Défaut: | Voir ci-dessous pour plus de détails
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, mpm_winnt

Cette directive permet de définir le nombre de threads que va créer chaque processus enfant. Un processus enfant crée ces threads au démarrage et n'en crée plus d'autres par la suite. Si l'on utilise un MPM comme mpm_winnt qui ne lance qu'un processus enfant, ce nombre doit être suffisamment grand pour supporter la charge du serveur. Avec un MPM comme worker qui lance plusieurs processus enfants, c'est le nombre total de threads qui doit être suffisamment grand pour supporter la charge du serveur.

La valeur par défaut de la directive ThreadsPerChild est 64 avec mpm_winnt, et 25 avec les autres MPMs.

Directive ThreadStackSize

Description: | La taille en octets de la pile qu'utilisent les threads qui traitent les connexions clients
Syntaxe: | ThreadStackSize taille
Défaut: | 65536 sous NetWare; varie en fonction des autres systèmes d'exploitation
Contexte: | configuration du serveur
Statut: | MPM
Module: | event, worker, mpm_winnt, mpm_netware, mpmt_os2
Compatibilité: | Disponible dans les versions 2.1 et supérieures du serveur HTTP Apache

La directive ThreadStackSize permet de définir la taille de la pile (pour les données propres) qu'utilisent les threads qui traitent les connexions clients en faisant appel à des modules. Dans la plupart des cas, la valeur par défaut de la taille de la pile du système d'exploitation convient, mais il existe certaines situations où il peut s'avérer nécessaire de l'ajuster :

  • Sur les plates-formes qui possèdent une valeur par défaut de taille de la pile relativement petite (par exemple HP-UX), Apache httpd peut se crasher si l'on utilise certains modules tiers qui possèdent un quantité de données propres stockées relativement importante. Il se peut que ces mêmes modules fonctionnent correctement sur d'autres plate-formes où la valeur par défaut de la taille de la pile est supérieure. Ce type de crash peut être evité en définissant ThreadStackSize à une valeur supérieure à la valeur par défaut du système d'exploitation. Ce type d'ajustement n'est nécessaire que si le fournisseur du module tiers en fait mention, ou si le diagnostic d'un crash d'Apache httpd indique que la taille de la pile était trop petite.
  • Sur les plates-formes où la taille par défaut de la pile des threads est sensiblement supérieure à la taille nécessaire pour la configuration du serveur web, il est possible de disposer d'un plus grand nombre de threads par processus enfant si la directive ThreadStackSize est définie à une valeur inférieure à la valeur par défaut du système d'exploitation. Cependant, ce type d'ajustement ne doit être effectué que dans un environnement de test permettant de qualifier le serveur web au maximum de ses possibilités, car il peut arriver, dans de rares cas, que des requêtes nécessitent une taille de pile supérieure pour pouvoir être traitées. La taille minimale requise pour la pile dépend fortement des modules utilisés, mais toute modification dans la configuration du serveur web peut invalider la définition courante de la directive ThreadStackSize.
  • Sous Linux, cette directive ne peut être utilisée que pour augmenter la valeur par defaut de la taille de la pile, car l'appel système sous-jacent utilise cette valeur comme taille de pile minimale. C'est la limite logicielle (souvent élevée) pour ulimit -s (8Mo si aucune limite) qui est utilisée comme taille de pile par défaut.
Il est recommandé de ne pas réduire ThreadStackSize, à moins qu'un grand nombre de threads par processus enfant ne soit nécessaire. Sur certaines plates-formes (y compris Linux), une valeur de 128000 est déjà trop basse et provoque des crashes avec certains modules courants.


event - Serveur Apache HTTP Version 2.4

Apache MPM event

Description: | Une variante du MPM worker conçue pour ne mobiliser des threads que pour les connexions en cours de traitement
Statut: | MPM
Identificateur de Module: | mpm_event_module
Fichier Source: | event.c

Sommaire

Le module multi-processus (MPM) event est conçu pour permettre le traitement d'un nombre accru de requêtes simultanées en déléguant certaines tâches aux threads d'écoute, libérant par là-même les threads de travail et leur permettant de traiter les nouvelles requêtes.

Pour utiliser le MPM event, ajoutez --with-mpm=event aux arguments du script configure lorsque vous compilez le programme httpd.

Traitement des bugs

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

Voir aussi

  • Le MPM worker

Relations avec le MPM Worker

Le MPM event s'inspire du MPM worker qui implémente un serveur hybride multi-processus et multi-threads. Un processus de contrôle unique (le parent) est chargé de lancer des processus enfants. Chaque processus enfant crée un nombre de threads serveurs défini via la directive ThreadsPerChild, ainsi qu'un thread d'écoute qui surveille les requêtes entrantes et les distribue aux threads de travail pour traitement au fur et à mesure de leur arrivée.

Les directives de configuration à l'exécution sont identiques à celles que propose le MPM worker, avec l'unique addition de la directive AsyncRequestWorkerFactor.

Comment tout cela fonctionne

Ce module MPM tente de résoudre le "problème keep alive" de HTTP. Lorsqu'un client a effectué une première requête, il peut garder la connexion ouverte et envoyer les requêtes suivante en utilisant le même socket, ce qui diminue considérablement la charge qui aurait été induite par la création de nouvelles connexions TCP. Cependant, le fonctionnement du serveur HTTP Apache impose de réserver un couple processus enfant/thread pour attendre les données en provenance du client, ce qui présente certains inconvénients. Pour résoudre ce problème, le MPM Event utilise un thread d'écoute dédié pour chaque processus pour gérer les sockets d'écoute, tous les sockets qui sont dans un état de connexion persistante, les sockets où les filtres de gestionnaire et de protocole ont fait leur travail, et ceux pour lesquels la seule chose restant à faire est l'envoi des données au client.

Cette nouvelle architecture, en exploitant les sockets non blocants et les fonctionnalités des noyaux modernes mis en valeur par APR (comme epoll de Linux), n'a plus besoin du Mutex mpm-accept pour éviter le problème de "thundering herd".

La directive AsyncRequestWorkerFactor permet de définir le nombre total de connexions qu'un bloc processus/thread peut gérer.

Connexions asynchrones

Avec les MPM précédents, les connexions asynchrones nécessitaient un thread de travail dédié, mais ce n'est plus le cas avec le MPM Event. La page d'état de mod_status montre de nouvelles colonnes dans la section "Async connections" :

Writing
Lors de l'envoi de la réponse au client, il peut arriver que le tampon d'écriture TCP soit plein si la connexion est trop lente. Si cela se produit, une instruction write() vers le socket renvoie en général EWOULDBLOCK ou EAGAIN pour que l'on puisse y écrire à nouveau après un certain temps d'inactivité. Le thread de travail qui utilise le socket doit alors être en mesure de récupérer la tâche en attente et la restituer au thread d'écoute qui, à son tour, la réattribuera au premier thread de travail disponible, lorsqu'un évènement sera généré pour le socket (par exemple, "il est maintenant possible d'écrire dans le socket"). Veuillez vous reporter à la section à propos des limitations pour plus de détails.
Keep-alive
La gestion des connexions persistantes constitue la principale amélioration par rapport au MPM Worker. Lorsqu'un thread de travail a terminé l'envoi d'une réponse à un client, il peut restituer la gestion du socket au thread d'écoute, qui à son tour va attendre un évènement en provenance du système d'exploitation comme "le socket est lisible". Si une nouvelle requête arrive en provenance du client, le thread d'écoute l'attribuera au premier thread de travail disponible. Inversement, si le délai KeepAliveTimeout est atteint, le socket sera fermé par le thread d'écoute. Les threads de travail n'ont donc plus à s'occuper des sockets inactifs et ils peuvent être réutilisés pour traiter d'autres requêtes.
Closing
Parfois, le MPM doit effectuer une fermeture progressive, c'est à dire envoyer au client une erreur survenue précédemment alors que ce dernier est en train de transmettre des données à httpd. Envoyer la réponse et fermer immédiatement la connexion n'est pas une bonne solution car le client (qui est encore en train d'envoyer le reste de la requête) verrait sa connexion réinitialisée et ne pourrait pas lire la réponse de httpd. La fermeture progressive est limitée dans le temps, mais elle peut tout de même être assez longue, si bien qu'elle est confiée à un thread de travail (y compris les procédures d'arrêt et la fermeture effective du socket). A partir de la version 2.4.28, c'est aussi le cas lorsque des connexions finissent par dépasser leur délai d'attente (le thread d'écoute ne gère jamais les connexions, si ce n'est attendre et dispatcher les évènements qu'elles génèrent).

Ces améliorations sont disponible pour les connexions HTTP ou HTTPS.

Arrêt de processus en douceur et utilisation du scoreboard

Ce MPM présentait dans le passé des limitations de montée en puissance qui provoquaient l'erreur suivante : "scoreboard is full, not at MaxRequestWorkers". La directive MaxRequestWorkers permet de limiter le nombre de requêtes pouvant être servies simultanément à un moment donné ainsi que le nombre de processus autorisés (MaxRequestWorkers / ThreadsPerChild), alors que le scoreboard représente l'ensemble des processus en cours d'exécution et l'état de leurs threads de travail. Si le scoreboard est plein (autrement dit si aucun des threads n'est dans un état inactif) et si le nombre de requêtes actives servies est inférieur à MaxRequestWorkers, cela signifie que certains d'entre eux bloquent les nouvelles requêtes qui pourraient être servies et sont en l'occurrence mises en attente (dans la limite de la valeur imposée par la directive ListenBacklog). La plupart du temps, ces threads sont bloqués dans un état d'arrêt en douceur car ils attendent de terminer leur travail sur une connexion TCP pour s'arrêter et ainsi libérer une entrée dans le scoreboard (par exemple dans le cas du traitement des requêtes de longue durée, des clients lents ou des connexions en keep-alive). Voici deux scénarios courants :

  • Pendant un graceful restart. Le processus parent demande à tous ses processus enfants de terminer leur travail et de s'arrêter pendant qu'il recharge la configuration et lance de nouveaux processus. Si les processus existants continuent de s'exécuter pendant un certain temps avant de s'arrêter, le scoreboard sera partiellement occupé jusqu'à ce que les entrées correspondantes soient libérées.
  • Lorsque la charge du serveur diminue suffisamment pour que httpd commence à stopper certains processus (par exemple pour respecter la valeur de la directive MaxSpareThreads). Cette situation est problèmatique car lorsque la charge augmente à nouveau, httpd va essayer de lancer de nouveaux processus. Si cette situation se répète, le nombre de processus peut augmenter sensiblement, aboutissant à un mélange d'anciens processus tentant de s'arrêter et de nouveaux processus tentant d'effectuer un travail quelconque.

A partir de la version 2.4.24, mpm-event est plus intelligent et peut traiter les arrêts graceful de manière plus efficace. Voici certaines de ces améliorations :

  • Utilisation de toutes les entrées du scoreboard dans la limite de la valeur définie par ServerLimit. Les directives MaxRequestWorkers et ThreadsPerChild permettent de limiter le nombre de processus actifs, alors que la directive ServerLimit prend aussi en compte les proccessus en arrêt graceful pour permettre l'utilisation d'entrées supplémentaires du scoreboard en cas de besoin. L'idée consiste à utiliser ServerLimit pour indiquer à httpd conbien de processus supplémentaires seront tolérés avant d'atteindre les limites imposées par les ressources du système.
  • Les processus en arrêt graceful doivent fermer leurs connexions en keep-alive.
  • Lors d'un arrêt graceful, s'il y a plus de threads de travail en cours d'exécution que de connexions ouvertes pour un processus donné, ces threads sont arrêtés afin de libérer les ressources plus vite (ce qui peut s'avérer nécessaire pour lancer de nouveaux processus).
  • Si le scoreboard est plein, empêche d'arrêter d'autres processus en mode graceful afin de réduire la charge jusqu'à ce que tous les anciens processus soient arrêtés (sinon la situation empirerait lors d'une remontée en charge).

Le comportement décrit dans le dernier point est bien visible via mod_status dans la table des connexions avec les deux nouvelles colonnes "Slot" et "Stopping". La première indique le PID et la seconde si le processus est en cours d'arrêt ou non ; l'état supplémentaire "Yes (old gen)" indique un processus encore en exécution après un redémarrage graceful.

Limitations

La gestion améliorée des connexions peut ne pas fonctionner pour certains filtres de connexion qui se sont déclarés eux-mêmes incompatibles avec le MPM Event. Dans ce cas, le MPM Event réadoptera le comportement du MPM worker et réservera un thread de travail par connexion. Notez que tous les modules inclus dans la distribution du serveur httpd sont compatibles avec le MPM Event.

Une restriction similaire apparaît lorsqu'une requête utilise un filtre en sortie qui doit pouvoir lire et/ou modifier la totalité du corps de la réponse. Si la connexion avec le client se bloque pendant que le filtre traite les données, et si la quantité de données produites par le filtre est trop importante pour être stockée en mémoire, le thread utilisé pour la requête n'est pas libéré pendant que httpd attend que les données soient transmises au client.
Pour illustrer ce cas de figure, nous pouvons envisager les deux situations suivantes : servir une ressource statique (comme un fichier CSS) ou servir un contenu issu d'un programme FCGI/CGI ou d'un serveur mandaté. La première situation est prévisible ; en effet, le MPM Event a une parfaite visibilité sur la fin du contenu, et il peut utiliser les évènements : le thread de travail qui sert la réponse peut envoyer les premiers octets jusqu'à ce que EWOULDBLOCK ou EAGAIN soit renvoyé, et déléguer le reste de la réponse au thread d'écoute. Ce dernier en retour attend un évènement sur le socket, et délègue le reste de la réponse au premier thread de travail disponible. Dans la deuxième situation par contre (FCGI/CGI/contenu mandaté), le MPM n'a pas de visibilité sur la fin de la réponse, et le thread de travail doit terminer sa tâche avant de rendre le contrôle au thread d'écoute. La seule solution consisterait alors à stocker la réponse en mémoire, mais ce ne serait pas l'option la plus sure en matière de stabilité du serveur et d'empreinte mémoire.

Matériel d'arrière-plan

Le modèle event a été rendu possible par l'introduction de nouvelles APIs dans les systèmes d'exploitation supportés :

  • epoll (Linux)
  • kqueue (BSD)
  • event ports (Solaris)

Avant que ces APIs soient mises à disposition, les APIs traditionnelles select et poll devaient être utilisées. Ces APIs deviennent lentes si on les utilise pour gérer de nombreuses connexions ou si le jeu de connexions possède un taux de renouvellement élevé. Les nouvelles APIs permettent de gérer beaucoup plus de connexions et leur performances sont meilleures lorsque le jeu de connexions à gérer change fréquemment. Ces APIs ont donc rendu possible l'écriture le MPM Event qui est mieux adapté à la situation HTTP typique où de nombreuses connexions sont inactives.

Le MPM Event suppose que l'implémentation de apr_pollset sous-jacente est raisonnablement sure avec l'utilisation des threads (threadsafe). Ceci évite au MPM de devoir effectuer trop verrouillages de haut niveau, ou d'avoir à réveiller le thread d'écoute pour lui envoyer un socket keep-alive. Ceci n'est possible qu'avec KQueue et EPoll.

Prérequis

Ce MPM dépend des opérations atomiques compare-and-swap d'APR pour la synchronisation des threads. Si vous compilez pour une plate-forme x86 et n'avez pas besoin du support 386, ou si vous compilez pour une plate-forme SPARC et n'avez pas besoin du support pre-UltraSPARC, ajoutez --enable-nonportable-atomics=yes aux arguments du script configure. Ceci permettra à APR d'implémenter les opérations atomiques en utilisant des instructions performantes indisponibles avec les processeurs plus anciens.

Ce MPM ne fonctionne pas de manière optimale sur les plates-formes plus anciennes qui ne gèrent pas correctement les threads, mais ce problème est sans objet du fait du prérequis concernant EPoll ou KQueue.

  • Pour utiliser ce MPM sous FreeBSD, la version 5.3 ou supérieure de ce système est recommandée. Il est cependant possible d'exécuter ce MPM sous FreeBSD 5.2.1 si vous utilisez libkse (voir man libmap.conf).
  • Pour NetBSD, il est recommander d'utiliser la version 2.0 ou supérieure.
  • Pour Linux, un noyau 2.6 est recommandé. Il faut aussi s'assurer que votre version de glibc a été compilée avec le support pour EPoll.

Directive AsyncRequestWorkerFactor

Description: | Limite le nombre de connexions simultanées par thread
Syntaxe: | AsyncRequestWorkerFactor facteur
Défaut: | 2
Contexte: | configuration du serveur
Statut: | MPM
Module: | event
Compatibilité: | Disponible depuis la version 2.3.13

Le MPM event gère certaines connexions de manière asynchrone ; dans ce cas, les threads traitant la requête sont alloués selon les besoins et pour de courtes périodes. Dans les autres cas, un thread est réservé par connexion. Ceci peut conduire à des situations où tous les threads sont saturés et où aucun thread n'est capable d'effectuer de nouvelles tâches pour les connexions asynchrones établies.

Pour minimiser les effets de ce problème, le MPM event utilise deux méthodes :

  • il limite le nombre de connexions simultanées par thread en fonction du nombre de processus inactifs;
  • si tous les processus sont occupés, il ferme des connexions permanentes, même si la limite de durée de la connexion n'a pas été atteinte. Ceci autorise les clients concernés à se reconnecter à un autre processus possèdant encore des threads disponibles.

Cette directive permet de personnaliser finement la limite du nombre de connexions par thread. Un processus n'acceptera de nouvelles connexions que si le nombre actuel de connexions (sans compter les connexions à l'état "closing") est inférieur à :

ThreadsPerChild + (AsyncRequestWorkerFactor * nombre de threads inactifs)

Il est possible d'effectuer une estimation du nombre maximum de connexions simultanées pour tous les processus et pour un nombre donné moyen de threads de travail inactifs comme suit :

(ThreadsPerChild + (AsyncRequestWorkerFactor * number of idle workers)) * ServerLimit

Exemple

ThreadsPerChild = 10
ServerLimit = 4
AsyncRequestWorkerFactor = 2
MaxRequestWorkers = 40

idle_workers = 4 (moyenne pour tous les processus pour faire simple)

max_connections = (ThreadsPerChild + (AsyncRequestWorkerFactor * idle_workers)) * ServerLimit
                = (10 + (2 * 4)) * 4 = 72

Lorsque tous les threads de travail sont inactifs, le nombre maximum absolu de connexions simultanées peut être calculé de manière plus simple :

(AsyncRequestWorkerFactor + 1) * MaxRequestWorkers

Exemple

ThreadsPerChild = 10
ServerLimit = 4
MaxRequestWorkers = 40
AsyncRequestWorkerFactor = 2

Si tous les threads de tous les processus sont inactifs, alors :

idle_workers = 10

Nous pouvons calculer le nombre maximum absolu de connexions simultanées de deux manières :

max_connections = (ThreadsPerChild + (AsyncRequestWorkerFactor * idle_workers)) * ServerLimit
                = (10 + (2 * 10)) * 4 = 120

max_connections = (AsyncRequestWorkerFactor + 1) * MaxRequestWorkers
                = (2 + 1) * 40 = 120

Le réglage de la directive AsyncRequestWorkerFactor nécessite de connaître le trafic géré par httpd pour chaque style d'utilisation spécifique ; si vous modifiez la valeur par défaut, vous devrez par conséquent effectuer des tests approfondis en vous appuyant étroitement sur les données fournies par mod_status.

La directive MaxRequestWorkers se nommait MaxClients avant la version 2.3.13. La valeur ci-dessus montre que cet ancien nom ne correspondait pas à sa signification exacte pour le MPM event.

La directive AsyncRequestWorkerFactor accepte des valeurs d'argument de type non entier, comme "1.5".


mod_unixd - Serveur Apache HTTP Version 2.4

Module Apache mod_unixd

Description: | Sécurité de base (nécessaire) pour les plates-formes de la famille Unix.
Statut: | Base
Identificateur de Module: | unixd_module
Fichier Source: | mod_unixd.c

Traitement des bugs

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

Voir aussi

  • Support de suEXEC

Directive ChrootDir

Description: | Répertoire dans lequel Apache doit se positionner au démarrage après avoir effectué un chroot(8).
Syntaxe: | ChrootDir chemin-répertoire
Défaut: | Non défini
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_unixd
Compatibilité: | Disponible depuis la version 2.2.10 d'Apache

Cette directive fait en sorte que le serveur effectue un chroot(8) vers le répertoire spécifié après le démarrage, mais avant d'accepter les requêtes en provenance du réseau.

Notez que l'exécution du serveur dans un environnement chroot n'est pas simple et nécessite une configuration particulière, en particulier si vous utilisez des scripts CGI ou PHP. Il est conseillé de se familiariser avec l'opération chroot avant d'essayer d'utiliser cette fonctionnalité.

Directive Group

Description: | Groupe sous lequel le serveur va traiter les requêtes
Syntaxe: | Group groupe unix
Défaut: | Group #-1
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_unixd

La directive Group permet de définir le groupe sous lequel le serveur va traiter les requêtes. Pour utiliser cette directive, le serveur doit avoir été démarré par root. Si vous démarrez le serveur en tant qu'utilisateur non root, celui-ci ne pourra pas adopter le groupe spécifié comme groupe d'exécution, et continuera à s'exécuter sous le groupe de l'utilisateur qui l'aura lancé. groupe unix peut se présenter sous la forme :

d'un nom de groupe
Référence le groupe spécifié par son nom.
du caractère # suivi d'un numéro de groupe.
Référence le groupe spécifié par son numéro.

Exemple

Group www-group

Il est conseillé de créer un groupe dédié à l'exécution du serveur. Certains administrateurs utilisent l'utilisateur nobody, mais ce n'est pas toujours souhaitable ou même possible.

Sécurité

Ne définissez pas la directive Group (ou User) à root à moins de savoir exactement ce que vous faites ainsi que les dangers encourus.

Voir aussi

  • VHostGroup
  • SuexecUserGroup

Directive Suexec

Description: | Active ou désactive la fonctionnalité suEXEC
Syntaxe: | Suexec On|Off
Défaut: | On si le binaire suexec existe avec les mode et propriétaire appropriés, Off dans le cas contraire
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_unixd

Lorsque cette directive est définie à On, le démarrage échouera si le binaire suexec n'existe pas, ou possède un propriétaire ou mode fichier invalide.

Lorsque cette directive est définie à Off, suEXEC sera désactivé, même si le binaire suexec existe et possède un propriétaire et mode fichier valides.

Directive User

Description: | L'utilisateur sous lequel le serveur va traiter les requêtes
Syntaxe: | User utilisateur unix
Défaut: | User #-1
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_unixd

La directive User permet de définir l'utilisateur sous lequel le serveur va traiter les requêtes. Pour utiliser cette directive, le serveur doit avoir été démarré par root. Si vous démarrez le serveur en tant qu'utilisateur non root, celui-ci ne pourra pas adopter l'utilisateur avec privilèges restreints comme utilisateur d'exécution, et continuera à s'exécuter sous l'utilisateur qui l'aura lancé. Si vous démarrez le serveur en tant que root, il est normal que le processus parent continue à s'exécuter sous root. utilisateur unix peut se présenter sous la forme :

d'un nom d'utilisateur
Référence l'utilisateur spécifié par son nom.
le caractère # suivi d'un numéro d'utilisateur.
Référence l'utilisateur spécifié par son numéro.

L'utilisateur ne doit pas posséder de privilèges qui lui permettraient d'accéder à des fichiers non destinés au monde extérieur, et parallèlement, l'utilisateur ne doit pas exécuter de code dont l'usage soit destiné à un usage autre que les requêtes HTTP. Il est conseillé de créer un utilisateur et un groupe dédiés à l'exécution du serveur. Certains administrateurs utilisent l'utilisateur nobody, mais ce n'est pas toujours souhaitable, car l'utilisateur nobody peut avoir diverses utilisations dans le système.

Sécurité

Ne définissez pas la directive Group (ou User) à root à moins de savoir exactement ce que vous faites ainsi que les dangers encourus.

Voir aussi

  • VHostUser
  • SuexecUserGroup


mpm_netware - Serveur Apache HTTP Version 2.4

Apache MPM netware

Description: | Module multi-processus implémentant un serveur web basé exclusivement sur les threads et optimisé pour Novell NetWare
Statut: | MPM
Identificateur de Module: | mpm_netware_module
Fichier Source: | mpm_netware.c

Sommaire

Ce module multi-processus (MPM) implémente un serveur web basé exclusivement sur les threads et optimisé pour Novell NetWare.

Le thread maître est chargé du lancement de threads esclaves qui attendent les connexions et les traitent au fur et à mesure de leur arrivée. Le serveur HTTP Apache essaie toujours de maintenir plusieurs threads esclaves en spare (en réserve) ou inactifs. De cette façon, les clients n'ont pas besoin d'attendre le lancement d'un nouveau thread enfant pour que leurs requêtes soient traitées.

Les directives StartThreads, MinSpareThreads, MaxSpareThreads, et MaxThreads contrôlent la manière dont le thread maître crée les threads esclaves afin de traiter les requêtes. En général, Apache httpd s'auto-régule correctement, et la plupart des sites ne nécessitent aucune modification des valeurs par défaut de ces directives. Pour les sites dont le serveur est limité en mémoire, il peut s'avérer nécessaire de diminuer la valeur de la directive MaxThreads afin d'éviter une hyper-activité du serveur (arrêts de threads inactifs et lancement incessant de nouveau threads). Vous trouverez plus d'informations à propos du contrôle de la création de processus dans le document conseils en matière de performances.

La directive MaxRequestsPerChild contrôle la fréquence à laquelle le serveur recycle ses processus en arrêtant les anciens et en en lançant de nouveaux. Sous le système d'exploitation NetWare, il est vivement recommandé de laisser cette directive à 0, ce qui permet aux threads esclaves de continuer à traiter les requêtes indéfiniment.

Traitement des bugs

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

Voir aussi

  • Définition des adresses et ports qu'utilise Apache httpd

Directive MaxThreads

Description: | Définit le nombre maximum de threads esclaves
Syntaxe: | MaxThreads nombre
Défaut: | MaxThreads 2048
Contexte: | configuration du serveur
Statut: | MPM
Module: | mpm_netware

La directive MaxThreads définit le nombre maximum de threads esclaves que l'on désire autoriser. La valeur par défaut correspondant à la valeur codée en dur à la compilation, la valeur de cette directive ne peut donc qu'être diminuée, comme dans l'exemple suivant :

MaxThreads 512


mpmt_os2 - Serveur Apache HTTP Version 2.4

Apache MPM os2

Description: | MPM hybride multi-processus, multi-thread pour OS/2
Statut: | MPM
Identificateur de Module: | mpm_mpmt_os2_module
Fichier Source: | mpmt_os2.c

Sommaire

Le serveur se compose d'un processus principal parent, et d'un petit nombre fixe de processus enfants.

La tâche du processus parent consiste à gérer les processus enfants, c'est à dire lancer ces processus de manière à ce qu'il y en ait toujours un nombre égal à la valeur de la directive StartServers pour traiter les connexions.

Chaque processus enfant comporte un jeu de threads esclaves et un thread maître qui accepte les connexions et les distribue aux esclaves via une file de travail. Le jeu de threads esclaves est dynamique et géré par un thread de maintenance de façon à ce que le nombre de threads inactifs soit maintenu entre MinSpareThreads et MaxSpareThreads.

Traitement des bugs

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

Voir aussi

  • Définition des adresses et ports qu'utilise Apache


prefork - Serveur Apache HTTP Version 2.4

Apache MPM prefork

Description: | Implémente un serveur web avec démarrage anticipé de processus, sans thread
Statut: | MPM
Identificateur de Module: | mpm_prefork_module
Fichier Source: | prefork.c

Sommaire

Ce module multi-processus (MPM) implémente un serveur web avec démarrage anticipé de processus. Chaque processus du serveur peut répondre aux requêtes entrantes, et un processus parent contrôle la taille du jeu de processus enfants. Il est particulièrement indiqué pour les sites qui ne doivent pas utiliser les threads afin de maintenir une compatibilité avec certaines bibliothèques non sûres du point de vue des threads. C'est également le MPM le plus approprié si l'on veut isoler les requêtes les unes des autres, de façon à ce qu'un problème concernant une requête n'affecte pas les autres.

Ce MPM s'auto-contrôle de manière efficace, de sorte qu'il est rarement nécessaire d'ajuster ses directives de configuration. Le plus important est la définition de la directive MaxRequestWorkers ; sa valeur doit être assez grande pour pouvoir traiter autant de requêtes simultanées que vous pensez recevoir, mais assez petite pour conserver suffisamment de mémoire RAM pour tous les processus.

Traitement des bugs

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

Voir aussi

  • Définition des adresses et ports qu'utilise le serveur HTTP Apache

Comment ça marche

Un processus de contrôle unique a pour tâche de lancer les processus enfants qui attendent les connexions et les traitent au fur et à mesure qu'elles arrivent. Apache httpd essaie toujours de maintenir plusieurs processus serveurs inactifs ou en réserve, afin de pouvoir traiter les requêtes entrantes. De cette façon, les clients n'ont pas besoin d'attendre le démarrage d'un nouveau processus enfant pour que leurs requêtes puissent être traitées.

Les directives StartServers, MinSpareServers, MaxSpareServers et MaxRequestWorkers permettent de contrôler la manière dont le processus parent crée les processus enfants pour traiter les requêtes. En général, Apache httpd s'auto-contrôle de manière efficace, de sorte que la plupart des sites peuvent conserver les valeurs par défaut des directives. Les sites qui doivent traiter plus de 256 requêtes simultanées doivent augmenter la valeur de MaxRequestWorkers, alors que les sites dont la ressource mémoire est limitée doivent la diminuer afin d'éviter une hyperactivité du serveur (utilisation excessive de la mémoire virtuelle sur disque). Vous trouverez plus d'informations à propos du contrôle de la création de processus dans le document conseils en matière de performances

Alors que le processus parent est en général démarré en tant que root sous Unix afin de pouvoir se mettre à l'écoute sur le port 80, les processus enfants sont lancés par Apache httpd sous un utilisateur avec privilèges restreints. On peut contrôler les privilèges accordés aux processus enfants d'Apache httpd à l'aide des directives User et Group. Les processus enfants doivent être en mesure de lire tous les contenus destinés à être servis, mais leurs privilèges doivent être aussi bas que possible.

La directive MaxConnectionsPerChild permet de contrôler la fréquence à laquelle le serveur recycle ses processus en arrêtant les plus anciens et en en lançant de nouveaux.

Ce module MPM utilise le mutex mpm-accept pour sérialiser l'accès aux connexions entrantes lorsque peut se présenter un problème d'afflux de requêtes (en général quand il y a plusieurs sockets en écoute). Les aspects de l'implémentation de ce mutex peuvent être configurés via la directive Mutex. Vous trouverez des informations supplémentaires à propos de ce mutex dans la documentation à propos des conseils en matière de performances

Directive MaxSpareServers

Description: | Nombre maximum de processus serveurs enfants inactifs
Syntaxe: | MaxSpareServers nombre
Défaut: | MaxSpareServers 10
Contexte: | configuration du serveur
Statut: | MPM
Module: | prefork

La directive MaxSpareServers permet de définir le nombre maximum souhaité de processus serveurs enfants inactifs. Un processus inactif est un processus qui ne traite pas de requête. S'il y a plus de MaxSpareServers processus inactifs, le processus parent arrêtera les processus excédentaires.

La modification de ce paramètre n'est nécessaire que dans le cas de sites très sollicités. Définir ce paramètre à une valeur très grande est cependant dans la plupart des cas une mauvaise idée. Si vous essayez d'affecter à ce paramètre une valeur égale ou inférieure à la valeur de MinSpareServers, le serveur HTTP Apache l'ajustera automatiquement à la valeur de MinSpareServers + 1.

Voir aussi

  • MinSpareServers
  • StartServers
  • MaxSpareThreads

Directive MinSpareServers

Description: | Nombre minimum de processus serveurs enfants inactifs
Syntaxe: | MinSpareServers nombre
Défaut: | MinSpareServers 5
Contexte: | configuration du serveur
Statut: | MPM
Module: | prefork

La directive MinSpareServers permet de définir le nombre minimum désiré de processus serveurs enfants inactifs. Un processus inactif est un processus qui ne traite pas de requête. S'il y a moins de MinSpareServers processus inactifs, le processus parent va créer de nouveaux enfants de la manière suivante : il en crée un, attend une seconde, il en crée deux, attend une seconde, il en crée quatre, puis continue ainsi exponentiellement jusu'à ce que son taux de création de processus enfants soit de 32 par seconde. Il ne s'arrête que lorsque le nombre de processus enfants correspond à la définition de la directive MinSpareServers.

La modification de ce paramètre n'est nécessaire que dans le cas de sites très sollicités. Définir ce paramètre à une valeur très grande est dans la plupart des cas une mauvaise idée.

Voir aussi

  • MaxSpareServers
  • StartServers
  • MinSpareThreads


mpm_winnt - Serveur Apache HTTP Version 2.4

Apache MPM winnt

Description: | Module multi-processus optimisé pour Windows NT.
Statut: | MPM
Identificateur de Module: | mpm_winnt_module
Fichier Source: | mpm_winnt.c

Sommaire

Ce module multi-processus (MPM) est le module par défaut pour les systèmes d'exploitation de style Windows NT. Il consiste en un processus de contrôle unique qui lance un processus enfant unique, ce dernier créant à son tour des threads pour traiter les requêtes.

La directive ThreadsPerChild définit le nombre maximal de connexions clientes simultanées.

Ce MPM utilise par défaut les APIs Windows avancées pour accepter les nouvelles connexions des clients. Avec certaines configurations, des produits tiers peuvent interférer avec cette implémentation, et provoquer l'enregistrement des messages suivants dans les journaux du serveur :

Child: Encountered too many AcceptEx faults accepting client connections.
winnt_mpm: falling back to 'AcceptFilter none'.

Le MPM se rabat sur une implémentation plus sûre, mais certaines requêtes n'ont pas été traitées correctement. Pour éviter cette erreur, définissez la directive AcceptFilter à none.

AcceptFilter http none
AcceptFilter https none

Avec les versions 2.0 et 2.2 d'Apache httpd, c'est la directive Win32DisableAcceptEx qui était utilisée à cet effet.

Le MPM WinNT diffère des autres MPMs Unix comme worker et event à bien des égards :

  • Lorsqu'un processus enfant s'arrête suite à un arrêt ou redémarrage du serveur, ou lorsque que la limite MaxConnectionsPerChild est atteinte, les requêtes en cours de traitement par ce processus en cours d'arrêt n'ont que TimeOut secondes pour s'exécuter avant l'arrêt du processus. Les autres types de redémarrage ou arrêt ne sont pas implémentés.
  • Les nouveau processus enfants relisent les fichiers de configuration au lieu d'en hériter du parent. Ce comportement ne pose pas de problème si le processus enfant est créé au démarrage ou redémarrage, mais dans le cas où un processus enfant est créé parce qu'un autre processus enfant s'est arrêté ou a atteint la limite MaxConnectionsPerChild, tout changement survenu entre temps dans la configuration sera alors pris en compte dans le processus enfant, et parent et enfant utiliseront une configuration différente. Si des modifications planifiées de la configuration ont été partiellement effectuées, et si la configuration courante n'est pas interprétable, le processus enfant de remplacement ne pourra pas démarrer, et le serveur s'arrêtera. En conséquence, toute modification des fichiers de configuration doit être accompagnée d'un redémarrage du serveur.
  • Les hooks monitor et fatal_exception ne sont pas encore implémentés.
  • La directive AcceptFilter est implémentée par le MPM et fournit un type de contrôle différent sur le traitement des nouvelles connexions (Voir la documentation de la directive AcceptFilter pour plus de détails).

Traitement des bugs

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

Voir aussi

  • Utiliser le serveur HTTP Apache sous Microsoft Windows


worker - Serveur Apache HTTP Version 2.4

Apache MPM worker

Description: | Module multi-processus implémentant un serveur web hybride multi-processus multi-thread
Statut: | MPM
Identificateur de Module: | mpm_worker_module
Fichier Source: | worker.c

Sommaire

Ce module multi-processus (MPM) implémente un serveur hybride multi-processus multi-thread. En utilisant les threads pour servir les requêtes, il peut en traiter un grand nombre tout en consommant moins de ressources qu'un serveur à base de processus. Cependant, il conserve une grande partie de la stabilité d'un serveur à base de processus en maintenant plusieurs processus disponibles, chacun de ces derniers possédant de nombreux threads.

Les directives les plus importantes qui permettent de contrôler ce MPM sont ThreadsPerChild, qui définit le nombre de threads lancés par chaque processus enfant et MaxRequestWorkers, qui définit le nombre global maximum de threads qui peuvent être lancés.

Traitement des bugs

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

Voir aussi

  • Définition des adresses et ports qu'utilise le serveur HTTP Apache

Comment ça marche

Un processus de contrôle unique (le parent) a pour tâche de lancer les processus enfants. Chaque processus enfant crée un nombre fixe de threads serveurs selon la valeur de la directive ThreadsPerChild, ainsi qu'un thread chargé d'attendre les connexions et de les passer à un thread serveur pour traitement au fur et à mesure de leur arrivée.

Le serveur HTTP Apache essaie toujours de maintenir un jeu de threads serveurs inactifs ou en réserve, qui se tiennent prêts à traiter les requêtes entrantes. De cette façon, les clients n'ont pas besoin d'attendre la création d'un nouveau thread ou d'un nouveau processus pour que leurs requêtes puissent être traitées. Le nombre de processus lancés initialement est défini par la directive StartServers. En cours de fonctionnement, le serveur évalue le nombre total de threads inactifs dans tous les processus, et en crée ou en arrête de façon à maintenir ce nombre à l'intérieur des limites définies par les directives MinSpareThreads et MaxSpareThreads. Comme ce module s'auto-contrôle de manière efficace, on peut en général conserver les valeurs par défaut. Le nombre maximum de clients pouvant être servis simultanément (c'est à dire le nombre global maximum de threads pour tous les processus) est défini par la directive MaxRequestWorkers. Le nombre maximum de processus enfants actifs est défini par la valeur de la directive MaxRequestWorkers divisée par la valeur de la directive ThreadsPerChild.

Deux directives permettent de fixer des limites absolues pour le nombre de processus enfants actifs et le nombre de threads serveurs par processus enfant, et ne peuvent être modifiées qu'en arrêtant complètement le serveur et en le démarrant à nouveau. La valeur de la directive ServerLimit constitue une limite absolue pour le nombre de processus enfants actifs, et doit être supérieure ou égale à la valeur de la directive MaxRequestWorkers divisée par la valeur de la directive ThreadsPerChild. La valeur de la directive ThreadLimit constitue une limite absolue pour le nombre de threads par processus enfant, et doit être supérieure ou égale à la valeur de la directive ThreadsPerChild.

En plus du jeu de processus enfants actifs, il peut exister quelques processus enfants en cours d'arrêt, mais dont au moins un thread serveur est encore en train de traiter une connexion client existante. Il peut subsister en théorie jusqu'à MaxRequestWorkers processus en cours d'arrêt, bien qu'en réalité, ce nombre sera en général beaucoup plus petit. Ce comportement peut être évité en désactivant l'arrêt de processus enfants individuels de la manière suivante :

  • définir la valeur de MaxConnectionsPerChild à zéro
  • Définir la valeur de MaxSpareThreads à la même valeur que MaxRequestWorkers

Voici un exemple typique de configuration du contrôle processus-thread pour le MPM worker :

ServerLimit         16
StartServers         2
MaxRequestWorkers  150
MinSpareThreads     25
MaxSpareThreads     75
ThreadsPerChild     25

Alors que le processus parent est en général démarré en tant que root sous Unix afin de se mettre en écoute du port 80, les processus enfants et les threads sont lancés par le serveur sous un utilisateur avec privilèges restreints. On peut utiliser les directives User et Group pour définir les privilèges des processus enfants. Les processus enfants doivent pouvoir être en mesure de lire tous les contenus destinés à être servis, mais doivent avoir des privilèges aussi bas que possible. De plus, ces directives définissent également les privilèges dont vont hériter les scripts CGI (sauf si on utilise suexec).

La directive MaxConnectionsPerChild permet de définir la fréquence à laquelle le serveur recycle ses processus en arrêtant les plus anciens et en en lançant de nouveaux.

Ce module MPM utilise le mutex mpm-accept pour sérialiser l'accès aux connexions entrantes lorsqu'un problème d'afflux de requêtes peut survenir (en général, lorsqu'il y a plusieurs sockets en écoute). Les différents aspects de l'implémentation de ce mutex peuvent être configurés via la directive Mutex. Vous trouverez des informations plus détaillées à propos de ce mutex dans la documentation sur les conseils en matière de performances.


mod_access_compat - Serveur Apache HTTP Version 2.4

Module Apache mod_access_compat

Description: | Autorisations de groupe à base de nom d'hôte (nom ou adresse IP)
Statut: | Extension
Identificateur de Module: | access_compat_module
Fichier Source: | mod_access_compat.c
Compatibilité: | Disponible dans la version 2.3 du serveur HTTP Apache à des fins de compatibilité avec les précédentes versions d'Apache httpd 2.x. Les directives fournies par ce module sont devenues obsolètes depuis la refonte d'authz. Voir mod_authz_host

Sommaire

Les directives fournies par le module mod_access_compat s'utilisent dans les sections <Directory>, <Files> et <Location>, ainsi que dans les fichiers .htaccess et permettent de contrôler l'accès à certaines parties du serveur. On peut contrôler cet accès en fonction du nom d'hôte du client, de son adresse IP ou d'autres caractéristiques de la requête, telles qu'elles sont enregistrées dans les variables d'environnement. Les directives Allow et Deny permettent de spécifier quels clients sont ou ne sont pas autorisés à accéder au serveur, alors que la directive Order définit le statut d'accès par défaut, et détermine la manière dont les directives Allow et Deny interagissent entre elles.

Les restrictions d'accès à base de nom d'hôte et l'authentification à base de mot de passe peuvent être implémentées simultanément. Dans ce cas, on utilise la directive Satisfy pour déterminer la manière dont ces deux modes de restrictions interagissent.

Note

Les directives fournies par le module mod_access_compat sont devenues obsolètes depuis la refonte du module mod_authz_host. Mélanger d'anciennes directives comme Order, Allow ou Deny avec des nouvelles comme Require est techniquement possible mais déconseillé. En effet, mod_access_compat a été conçu pour supporter des configurations ne contenant que des anciennes directives afin de faciliter le passage à la version 2.4. Voir le document upgrading pour plus de détails.

En général, les directives de restriction d'accès s'appliquent à toutes les méthodes d'accès (GET, PUT, POST, etc...). C'est d'ailleurs ce que l'on souhaite dans la plupart des cas. Il est cependant possible de restreindre certaines méthodes, alors que les autres méthodes ne se verront imposée aucune restriction, en regroupant les directives à l'intérieur d'une section <Limit>.

Fusion des sections de configuration

Lorsqu'une directive fournie par ce module est utilisée dans une nouvelle section de configuration, cette dernière n'hérite d'aucune directive définie dans une section précédente.

Traitement des bugs

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

Voir aussi

  • Require
  • mod_authz_host
  • mod_authz_core

Directive Allow

Description: | Spécifie quels hôtes peuvent accéder à une certaine zone du serveur
Syntaxe: | Allow from all|hôte|env=[!]variable d'environnement [hôte|env=[!]variable d'environnement] ...
Contexte: | répertoire, .htaccess
AllowOverride: | Limit
Statut: | Extension
Module: | mod_access_compat

La directive Allow permet de définir quels hôtes ont le droit d'accéder à une certaine partie du serveur. On peut contrôler l'accès par nom d'hôte, adresse IP, intervalle d'adresses IP, ou toute autre caractéristique de la requête client enregistrée dans les variables d'environnement.

Le premier argument de cette directive est toujours from. Les arguments suivants peuvent prendre trois formes différentes. Si Allow from all est spécifié, tout hôte se voit accordé l'accès, en tenant compte des directives Deny et Order comme décrit plus loin. Pour ne permettre l'accès au serveur qu'à un hôte ou un groupe d'hôtes particuliers, on peut spécifier un nom d'hôte sous une des formes suivantes :

Un nom de domaine (partiel)
Allow from example.org
Allow from .net example.edu

Les hôtes dont les noms correspondent ou se terminent par la chaîne spécifiée ont l'autorisation d'accès. Seules les composantes entières du nom d'hôte doivent correspondre ; ainsi, dans l'exemple ci-dessus, foo.example.org correspondra, mais fooexample.org ne conviendra pas. Avec cette configuration, Apache httpd va effectuer une double recherche DNS sur l'adresse IP du client, sans tenir compte de la définition de la directive HostnameLookups. Tout d'abord, une recherche DNS inverse sur l'adresse IP est effectuée pour déterminer le nom d'hôte associé, puis une recherche directe sur le nom d'hôte est effectuée afin de s'assurer qu'il correspond bien à l'adresse IP originale. L'accès ne sera accordé que si le nom d'hôte correspond et si les recherches DNS inverse et directe concordent.

Une adresse IP complète
Allow from 10.1.2.3
Allow from 192.168.1.104 192.168.1.205

L'adresse IP d'un hôte auquel on a accordé l'accès

Une adresse IP partielle
Allow from 10.1
Allow from 10 172.20 192.168.2

De un à trois des premiers octets d'une adresse IP, afin de restreindre l'accès à un sous-réseau.

Une paire réseau/masque de sous-réseau
Allow from 10.1.0.0/255.255.0.0

Un réseau a.b.c.d, et un masque de sous-réseau w.x.y.z, pour une définition plus précise de la restriction d'accès imposée à un sous-réseau.

Une spécification CIDR réseau/nnn
Allow from 10.1.0.0/16

Identique au cas précédent, mis à part que le masque est constitué des nnn bits de poids fort.

Notez que les trois derniers exemples désignent le même ensemble d'hôtes.

On peut spécifier des adresses et sous-réseaux IPv6 de la manière suivante :

Allow from 2001:db8::a00:20ff:fea7:ccea
Allow from 2001:db8::a00:20ff:fea7:ccea/10

Le troisième format d'argument de la directive Allow permet de contrôler l'accès au serveur en fonction de l'existence d'une variable d'environnement. Lorsque Allow from env=variable d'environnement est spécifié, la requête est autorisée si la variable d'environnement variable d'environnement existe. En revanche, lorsque Allow from env=!env-variable est spécifié, la requête est autorisée si la variable d'environnement variable d'environnement n'existe pas. Le serveur permet de définir avec souplesse des variables d'environnement en se basant sur les caractéristiques de la requête client et en utilisant les directives fournies par le module mod_setenvif. Ainsi, on peut utiliser la directive Allow pour permettre l'accès en fonction de paramètres comme le User-Agent (type de navigateur) des clients, le Referer, ou d'autres champs d'en-tête de la requête HTTP.

SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
<Directory "/docroot">
    Order Deny,Allow
    Deny from all
    Allow from env=let_me_in
</Directory>

Dans cet exemple, les navigateurs dont la chaîne user-agent commence par KnockKnock/2.0 se verront accorder l'accès, alors que tous les autres seront rejetés.

Fusion des sections de configuration

Lorsqu'une directive fournie par ce module est utilisée dans une nouvelle section de configuration, cette dernière n'hérite d'aucune directive définie dans une section précédente.

Directive Deny

Description: | Définit quels hôtes ne sont pas autorisés à accéder au serveur
Syntaxe: | Deny from all|hôte|env=[!]variable d'environnement [hôte|env=[!]variable d'environnement] ...
Contexte: | répertoire, .htaccess
AllowOverride: | Limit
Statut: | Extension
Module: | mod_access_compat

Cette directive permet de restreindre l'accès au serveur en fonction du nom d'hôte, de l'adresse IP ou de variables d'environnement. Les arguments de la directive Deny sont identiques aux arguments de la directive Allow.

Directive Order

Description: | Définit le statut d'accès par défaut et l'ordre dans lequel les directives Allow et Deny sont évaluées.
Syntaxe: | Order ordre
Défaut: | Order Deny,Allow
Contexte: | répertoire, .htaccess
AllowOverride: | Limit
Statut: | Extension
Module: | mod_access_compat

La directive Order, associée aux directives Allow et Deny, implémente un système de contrôle d'accès en trois passes. Au cours de la première passe, ce sont soit toutes les directives Allow, soit toutes les directives Deny qui sont traitées, selon la définition de la directive Order. Le reste des directives (Deny ou Allow) est traité au cours de la seconde passe. La troisième passe s'applique à toutes les requêtes qui ne sont concernées par aucune des deux premières passes.

Notez que toutes les directives Allow et Deny sont traitées, à la différence d'un pare-feu classique où seule la première règle qui correspond est utilisée. La dernière directive qui correspond s'applique ( à la différence là encore d'un pare-feu classique). De plus, l'ordre dans lequel les lignes apparaissent dans le fichier de configuration n'a pas d'incidence -- toutes les lignes Allow sont considérées comme un groupe, toutes les lignes Deny comme un autre, et le statut par défaut a son existence propre.

Ordre peut être :

Allow,Deny
Dans un premier temps, toutes les directives Allow sont évaluées ; au moins une d'entre elles doit correspondre, sinon la requête est rejetée. Ensuite, toutes les directives Deny sont évaluées. Si au moins l'une d'entre elles correspond, la requête est rejetée. Enfin, toute requête qui ne correspond à aucune directive Allow ou Deny est rejetée par défaut.
Deny,Allow
Dans un premier temps, toutes les directives Deny sont évaluées ; Si au moins une d'entre elles correspond, la requête est rejetée, à moins qu'elle corresponde aussi à une directive Allow. Toute requête qui ne correspond à aucune directive Allow ou Deny est autorisée.
Mutual-failure
Cet argument a le même effet que Allow,Deny et est devenu de ce fait obsolète.

Les mots-clés ne peuvent être séparés que par des virgules ; aucun espace ne doit s'intercaler entre eux.

Match | Résultat Allow,Deny | Résultat Deny,Allow
Correspond à Allow seulement | Requête autorisée | Requête autorisée
Correspond à Deny seulement | Requête rejetée | Requête rejetée
Aucune correspondance | Par défaut la seconde directive : rejet | Par défaut la seconde directive : autorisation
Correspond à Allow & Deny | La dernière correspondance l'emporte : rejet | La dernière correspondance l'emporte : autorisation

Dans cet exemple, tous les hôtes du domaine example.org ont l'autorisation d'accès ; tous les autres voient leur accès refusé.

Order Deny,Allow
Deny from all
Allow from example.org

Dans l'exemple suivant, tous les hôtes du domaine example.org ont l'autorisation d'accès, sauf ceux du sous-domaine foo.example.org qui voient leur accès refusé. Tous les hôtes qui ne sont pas dans le domaine example.org sont rejetés car le statut par défaut est positionné sur Deny, et consiste donc en un refus d'accès.

Order Allow,Deny
Allow from example.org
Deny from foo.example.org

Par contre, si la valeur de la directive Order, dans l'exemple précédent, est Deny,Allow, tout le monde a l'autorisation d'accès. Ceci est dû au fait que Allow from example.org sera évalué en dernier, sans tenir compte de l'ordre réel dans lequel les directives apparaissent dans le fichier de configuration, et va l'emporter sur Deny from foo.example.org. Tout hôte qui n'est pas dans le domaine example.org aura aussi l'autorisation d'accès car le statut par défaut est positionné sur Allow et constitue donc une autorisation d'accès.

La présence d'une directive Order peut affecter le contrôle d'accès à une partie du serveur même en l'abscence de directives Allow et Deny associées, à cause de son influence sur le statut par défaut. Par exemple,

<Directory "/www">
    Order Allow,Deny
</Directory>

va interdire tout accès au répertoire /www à cause du statut d'accès par défaut qui est défini à Deny.

La directive Order ne contrôle l'ordre dans lequel sont traitées les directives d'accès qu'au cours de chaque phase du traitement de la configuration du serveur. Ceci implique, par exemple, qu'une directive Allow ou Deny située dans une section <Location> sera toujours évaluée après une directive Allow ou Deny située dans une section <Directory> ou un fichier .htaccess, sans tenir compte de la définition de la directive Order. Pour plus de détails à propos de la fusion des sections de configuration, voir le document Comment fonctionnent les sections Directory, Location et Files.

Fusion des sections de configuration

Lorsqu'une directive fournie par ce module est utilisée dans une nouvelle section de configuration, cette dernière n'hérite d'aucune directive définie dans une section précédente.

Directive Satisfy

Description: | Interaction entre le contrôle d'accès en fonction de l'hôte et l'authentification utilisateur
Syntaxe: | Satisfy Any|All
Défaut: | Satisfy All
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_access_compat
Compatibilité: | Affecté par <Limit> et <LimitExcept> à partir de la version 2.0.51

Politique d'accès dans le cas où on utilise à la fois Allow et Require. L'argument est soit All, soit Any. L'utilisation de cette directive n'a de sens que si l'accès à une zone particulière du serveur est restreinte par utilisateur/mot de passe et en fonction de l'adresse IP de l'hôte client. Dans ce cas, par défaut (All), le client doit satisfaire à la restriction d'adresse, et fournir un couple utilisateur/mot de passe valide. Avec l'argument Any, le client se verra accorder l'accès s'il satisfait à la restriction d'adresse ou fournit un couple utilisateur/mot de passe valide. On peut utiliser cette dernière définition pour restreindre l'accès à une zone par mot de passe, mais accorder l'accès aux clients possédant certaines adresses IP sans qu'ils aient à fournir de mot de passe.

Par exemple, si vous souhaitez que les utilisateurs de votre réseau accèdent à une zone de votre site web sans restriction, mais que l'accès à cette zone nécessite un mot de passe pour les autres utilisateurs, vous pouvez utiliser une configuration du style :

Require valid-user
Allow from 192.168.1
Satisfy Any

Une autre utilisation fréquente de la directive Satisfy est l'allègement des restrictions d'accès à un sous-répertoire par rapport aux restrictions d'accès au répertoire parent :

<Directory "/var/www/private">
    Require valid-user
</Directory>

<Directory "/var/www/private/public">
    Allow from all
    Satisfy Any
</Directory>

Dans l'exemple ci-dessus, l'accès au répertoire /var/www/private nécessitera une authentification, alors que l'accès au répertoire /var/www/private/public sera accordé sans restriction.

Depuis la version 2.0.51, les directives Satisfy peuvent être restreintes à certaines méthodes particulières à l'aide des sections <Limit> et <LimitExcept>.

Fusion des sections de configuration

Lorsqu'une directive fournie par ce module est utilisée dans une nouvelle section de configuration, cette dernière n'hérite d'aucune directive définie dans une section précédente.

Voir aussi

  • Allow
  • Require


mod_actions - Serveur Apache HTTP Version 2.4

Module Apache mod_actions

Description: | Exécution des scripts CGI en fonction du type de média ou de la méthode de requête.
Statut: | Base
Identificateur de Module: | actions_module
Fichier Source: | mod_actions.c

Sommaire

Ce module possède deux directives. La directive Action vous permet de lancer l'exécution de scripts CGI chaque fois qu'un fichier possédant un certain type de contenu MIME fait l'objet d'une requête. La directive Script vous permet de lancer l'exécution de scripts CGI chaque fois que la requête utilise une méthode particulière. Ceci facilite grandement l'exécution de scripts qui traitent des fichiers.

Traitement des bugs

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

Voir aussi

  • mod_cgi
  • Contenu dynamique avec CGI
  • Utilisation des gestionnaires d'Apache httpd

Directive Action

Description: | Active un script CGI pour un gestionnaire ou un type de contenu particulier
Syntaxe: | Action type d'action script cgi [virtual]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_actions
Compatibilité: | Le modificateur virtual et le passage de gestionnaire ont été introduits dans Apache 2.1

Cette directive ajoute une action qui va activer script cgi lorsque type d'action est déclenché par la requête. script cgi est un chemin URL vers une ressource qui a été désignée comme script CGI à l'aide des directives ScriptAlias ou AddHandler. type d'action peut être soit un gestionnaire, soit un type de contenu MIME. L'URL et le chemin du document correspondant sont envoyés en utilisant les variables d'environnement CGI standards PATH_INFO et PATH_TRANSLATED. Le gestionnaire utilisé pour cette requête particulière est transmis à l'aide de la variable REDIRECT_HANDLER.

Exemple : type MIME

# Requests for files of a particular MIME content type:
Action image/gif /cgi-bin/images.cgi

Dans cet exemple, les requêtes pour des fichiers possédant le type de contenu MIME image/gif seront traitées par le script CGI /cgi-bin/images.cgi.

Example: File extension

# Files of a particular file extension
AddHandler my-file-type .xyz
Action my-file-type "/cgi-bin/program.cgi"

Dans cet exemple, les requêtes pour des fichiers possédant l'extension .xyz seront traitées par le script CGI /cgi-bin/programme.cgi.

Le modificateur optionnel virtual permet de désactiver la vérification de l'existence du fichier demandé. Ceci peut s'avérer utile, par exemple, si vous voulez utiliser la directive Action pour des localisations virtuelles.

<Location "/news">
    SetHandler news-handler
    Action news-handler "/cgi-bin/news.cgi" virtual
</Location>

Voir aussi

  • AddHandler

Directive Script

Description: | Active un script CGI dans le cas d'une méthode de requête particulière.
Syntaxe: | Script méthode script cgi
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_actions

Cette directive ajoute une action qui va activer script cgi lorsqu'un fichier est demandé en utilisant la méthode méthode. script cgi est le chemin URL d'une ressource qui a été désignée comme script CGI en utilisant les directives ScriptAlias ou AddHandler. L'URL et le chemin du document demandé sont envoyés en utilisant les variables d'environnement CGI standards PATH_INFO et PATH_TRANSLATED.

Tous les noms de méthode peuvent être utilisés. Les noms de méthode sont sensibles à la casse, si bien que Script PUT et Script put ont des effets totalement différents.

Notez que la commande Script ne définit que des actions par défaut. Si un script CGI est appelé, ou toute autre ressource capable de gérer la méthode de la requête en interne, il agira en conséquence. Notez aussi que Script avec une méthode GET ne sera appelé que si la requête possède des arguments (par exemple foo.html?hi). Dans le cas contraire, la requête sera traitée normalement.

# All GET requests go here
Script GET "/cgi-bin/search"

# A CGI PUT handler
Script PUT "/~bob/put.cgi"


mod_alias - Serveur Apache HTTP Version 2.4

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

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 du serveur, 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>

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 du serveur, 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 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 du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | 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 POSTs 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 du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | 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 du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | 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 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 du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | 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 du serveur, 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 du serveur, 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.


mod_allowmethods - Serveur Apache HTTP Version 2.4

Module Apache mod_allowmethods

Description: | Ce module permet de restreindre aisément les méthodes HTTP pouvant être utilisées sur le serveur
Statut: | Expérimental
Identificateur de Module: | allowmethods_module
Fichier Source: | mod_allowmethods.c

Sommaire

Ce module permet de restreindre aisément les méthodes HTTP pouvant être utilisées sur le serveur. La configuration la plus courante est du style :

<Location "/">
   AllowMethods GET POST OPTIONS
</Location>

Directive AllowMethods

Description: | Restreint l'accès aux méthodes HTTP spécifiées
Syntaxe: | AllowMethods reset|HTTP-method [HTTP-method]...
Défaut: | AllowMethods reset
Contexte: | répertoire
Statut: | Expérimental
Module: | mod_allowmethods

Les noms des méthodes HTTP sont sensibles à la casse, et sont en général définis en majuscules, comme dans les RFCs. Les méthodes GET et HEAD sont considérées comme équivalentes. Le mot-clé reset permet de désactiver mod_allowmethods dans les niveaux inférieurs d'imbrication :

<Location "/svn">
   AllowMethods reset
</Location>

Avertissement

La méthode TRACE ne peut pas être rejetée par ce module ; pour ce faire, vous devez utiliser la directive TraceEnable.

Le module mod_allowmethods a été écrit pour remplacer l'implémentation "bricolée" des directives Limit et LimitExcept.


mod_asis - Serveur Apache HTTP Version 2.4

Module Apache mod_asis

Description: | Envoie des fichiers contenant leurs propres en-têtes HTTP
Statut: | Base
Identificateur de Module: | asis_module
Fichier Source: | mod_asis.c

Sommaire

Ce module fournit le gestionnaire send-as-is qui permet au serveur HTTP Apache d'envoyer le document sans ajouter la plupart des en-têtes HTTP habituels.

On peut l'utiliser pour envoyer tous types de données en provenance du serveur, y compris les redirections et autres réponses HTTP spéciales, sans devoir faire appel à un script CGI ou nph.

Pour des raisons historiques, ce module traitera aussi tout fichier dont le type MIME est httpd/send-as-is.

Traitement des bugs

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

Voir aussi

  • mod_headers
  • mod_cern_meta
  • Utilisation des gestionnaires d'Apache httpd

Mode d'emploi

Dans le fichier de configuration, associez les fichiers asis au gestionnaire send-as-is comme ceci :

AddHandler send-as-is asis

Le contenu de tout fichier possédant l'extension .asis sera envoyé par Apache httpd au client pratiquement tel quel. En particulier, les en-têtes HTTP seront déduits du fichier lui-même selon les règles du module mod_cgi, si bien qu'un fichier asis doit inclure des en-têtes valides, et utiliser l'en-tête CGI Status: pour déterminer le code de réponse HTTP. L'en-tête Content-Length: sera automatiquement inséré ou, s'il est déjà présent, corrigé par httpd.

Voici un exemple de fichier dont le contenu est envoyé tel quel pour informer un client qu'un fichier a été déplacé.

Status: 301 Ou se trouve cette URL maintenant
Location: http://xyz.example.com/foo/bar.html
Content-type: text/html

<html>
<head>
<title>Mauvaises excuses</title>
</head>
<body>
<h1>La merveilleuse page de Fred a été déplacée vers
<a href="http://xyz.example.com/foo/bar.html">le site de Joe</a>.
</h1>
</body>
</html>

Notes :

Le serveur ajoute systématiquement les en-têtes Date: et Server: aux données qu'il envoie au client, si bien qu'ils n'ont pas besoin d'être inclus dans le fichier. Le serveur n'ajoute pas d'en-tête Last-Modified, ce qu'il devrait probablement faire.


mod_auth_basic - Serveur Apache HTTP Version 2.4

Module Apache mod_auth_basic

Description: | Authentification HTTP de base
Statut: | Base
Identificateur de Module: | auth_basic_module
Fichier Source: | mod_auth_basic.c
Compatibilité: | Disponible depuis la version 2.1 d'Apache

Sommaire

Ce module permet d'utiliser l'authentification basique HTTP pour restreindre l'accès en recherchant les utilisateurs dans les fournisseurs d'authentification spécifiés. Il est en général combiné avec au moins un module d'authentification comme mod_authn_file et un module d'autorisation comme mod_authz_user. L'authentification HTTP à base de condensé (digest), quant à elle, est fournie par le module mod_auth_digest.

Traitement des bugs

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

Voir aussi

  • AuthName
  • AuthType
  • Require
  • Mode d'emploi de l'authentification

Directive AuthBasicAuthoritative

Description: | Définit si les processus d'autorisation et d'authentification peuvent être confiés à des modules de plus bas niveau
Syntaxe: | AuthBasicAuthoritative On|Off
Défaut: | AuthBasicAuthoritative On
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_auth_basic

Normalement, chaque module d'autorisation énuméré dans la directive AuthBasicProvider va tenter de vérifier l'utilisateur, et si ce dernier n'est trouvé dans aucun des fournisseurs, l'accès sera refusé. Définir explicitement la directive AuthBasicAuthoritative à Off permet de confier l'autorisation et l'authentification à d'autres modules non basés sur les fournisseurs si aucun identifiant utilisateur ou aucune règle ne correspondent à l'identifiant utilisateur spécifié. Ceci ne peut s'avérer nécessaire que lorsque mod_auth_basic est combiné avec des modules tiers qui n'ont pas été configurés à l'aide de la directive AuthBasicProvider. Lorsqu'on utilise de tels modules, l'ordre dans lequel s'effectue le traitement est défini dans le code source des modules et n'est pas configurable.

Directive AuthBasicFake

Description: | Authentification de base simulée à l'aide des nom d'utilisateur et mot de passe fournis
Syntaxe: | AuthBasicFake off|username [password]
Défaut: | none
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_auth_basic
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

Les nom d'utilisateur et mot de passe spécifiés sont rassemblés dans un en-tête d'autorisation qui est transmis au serveur ou au service sous-jacent au serveur. Ces nom d'utilisateur et mot de passe sont interprétés par l'interpréteur d'expression, ce qui permet de les définir en fonction de paramètres de la requête.

Si aucun mot de passe n'est spécifié, la valeur par défaut "password" sera utilisée. Pour désactiver l'authentification de base simulée pour un espace d'URL, définissez AuthBasicFake à "off".

Dans l'exemple suivant, un nom d'utilisateur et un mot de passe prédéfinis sont transmis à un serveur d'arrière-plan :

Exemple de transmission d'un nom d'utilisateur et d'un mot de passe prédéfinis

<Location "/demo">
    AuthBasicFake demo demopass
</Location>

Dans l'exemple suivant, l'adresse email extraite d'un certificat client est transmise au serveur, étendant par là-même la fonctionnalité de l'option FakeBasicAuth de la directive SSLOptions. Comme avec l'option FakeBasicAuth, le mot de passe se voit attribué le contenu fixe de la chaîne "password".

Exemple d'utilisation avec un certificat

<Location "/secure">
    AuthBasicFake "%{SSL_CLIENT_S_DN_Email}"
</Location>

Pour compléter l'exemple précédent, il est possible de générer la valeur du mot de passe en procédant à un hashage de l'adresse email à partir d'un mot d'une passphrase initial fixée, puis de transmettre le résultat obtenu au serveur d'arrière-plan. Ceci peut s'avérer utile pour donner accès à des serveurs anciens qui ne supportent pas les certificats clients.

Exemple de génération de mot de passe par hashage de l'adresse email

<Location "/secure">
    AuthBasicFake "%{SSL_CLIENT_S_DN_Email}" "%{sha1:passphrase-%{SSL_CLIENT_S_DN_Email}}"
</Location>

Désactivation de l'authentification simulée

<Location "/public">
    AuthBasicFake off
</Location>

Directive AuthBasicProvider

Description: | Définit le(les) fournisseur(s) d'authentification pour cette zone du site web
Syntaxe: | AuthBasicProvider nom fournisseur [nom fournisseur] ...
Défaut: | AuthBasicProvider file
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_auth_basic

La directive AuthBasicProvider permet de définir le fournisseur utilisé pour authentifier les utilisateurs pour la zone du site web concernée. Le fournisseur par défaut file est implémenté par le module mod_authn_file. Assurez-vous que le module implémentant le fournisseur choisi soit bien présent dans le serveur.

Exemple

<Location "/secure">
    AuthType basic
    AuthName "private area"
    AuthBasicProvider  dbm
    AuthDBMType        SDBM
    AuthDBMUserFile    "/www/etc/dbmpasswd"
    Require            valid-user
</Location>

Les fournisseurs sont sollicités dans l'ordre jusqu'à ce que l'un d'entre eux trouve une correspondance pour le nom d'utilisateur de la requête ; alors, ce dernier fournisseur sera le seul à vérifier le mot de passe. Un échec dans la vérification du mot de passe n'entraîne pas le passage du contrôle au fournisseur suivant.

Les différents fournisseurs disponibles sont implémentés par les modules mod_authn_dbm, mod_authn_file, mod_authn_dbd, mod_authnz_ldap et mod_authn_socache.

Directive AuthBasicUseDigestAlgorithm

Description: | Vérifie les mots de passe auprès des fournisseurs d'authentification à la manière de l'authentification de type Digest.
Syntaxe: | AuthBasicUseDigestAlgorithm MD5|Off
Défaut: | AuthBasicUseDigestAlgorithm Off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_auth_basic
Compatibilité: | Disponible à partir de la version 2.4.7 du serveur HTTP Apache

Normalement, lorsqu'on utilise l'authentification basique, les fournisseurs spécifiés via la directive AuthBasicProvider tentent de contrôler l'identité d'un utilisateur en recherchant dans leurs bases de données l'existence d'un couple utilisateur/mot de passe correspondant. Les mots de passe enregistrés sont en général chiffrés, mais ce n'est pas systématique ; chaque fournisseur peut choisir son propre mode de stockage des mots de passe.

Lorsqu'on utilise l'authentification de type Digest, les fournisseurs spécifiés par la directive AuthDigestProvider effectuent une recherche similaire dans leurs bases de données pour trouver un couple utilisateur/mot de passe correspondant. Cependant, à la différence de l'authentification basique, les données associées à chaque utilisateur et comportant le nom d'utilisateur, le domaine de protection (realm) et le mot de passe doivent être contenues dans une chaîne chiffrée (Voir le document RFC 2617, Section 3.2.2.2 pour plus de détails à propos du type de chiffrement utilisé pour cette chaîne).

A cause de la différence entre les méthodes de stockage des données des authentifications de type basique et digest, le passage d'une méthode d'authentification de type digest à une méthode d'authentification de type basique requiert l'attribution de nouveaux mots de passe à chaque utilisateur, car leur mots de passe existant ne peut pas être extrait à partir du schéma de stockage utilisé par les fournisseurs d'authentification de type digest.

Si la directive AuthBasicUseDigestAlgorithm est définie à la valeur MD5, le mot de passe d'un utilisateur dans le cas de l'authentification basique sera vérifié en utilisant le même format de chiffrement que dans le cas de l'authentification de type digest. Tout d'abord, une chaîne comportant le nom d'utilisateur, le domaine de protection (realm) et le mot de passe est générée sous forme de condensé (hash) en utilisant l'algorithme MD5 ; puis le nom d'utilisateur et cette chaîne chiffrée sont transmis aux fournisseurs spécifiés via la directive AuthBasicProvider comme si la directive AuthType était définie à Digest et si l'authentification de type Digest était utilisée.

Grâce à cette directive, un site peut basculer d'une authentification de type digest à basique sans devoir changer les mots de passe des utilisateurs.

Le processus inverse consistant à passer d'une authentification de type basique à digest sans changer les mots de passe n'est en général pas possible. Les mots de passe enregistrés dans le cas d'une authentification de type basique ne pourront être extraits et chiffrés à nouveau selon le schéma de l'authentification de type digest, que s'ils ont été stockés en clair ou selon un schéma de chiffrement réversible.
Seuls les fournisseurs qui supportent l'authentification de type digest pourront authentifier les utilisateurs lorsque la directive AuthBasicUseDigestAlgorithm est définie à MD5. L'utilisation d'un autre fournisseur provoquera un message d'erreur et le client se verra refuser l'accès.


mod_auth_digest - Serveur Apache HTTP Version 2.4

Module Apache mod_auth_digest

Description: | Authentification utilisateur utilisant les condensés MD5
Statut: | Extension
Identificateur de Module: | auth_digest_module
Fichier Source: | mod_auth_digest.c

Sommaire

Ce module implémente l'authentification HTTP basée sur les condensés MD5 (RFC2617), et fournit une alternative à mod_auth_basic en ne transmettant plus le mot de passe en clair. Cependant, cela ne suffit pas pour améliorer la sécurité de manière significative par rapport à l'authentification basique. En outre, le stockage du mot de passe sur le serveur est encore moins sûr dans le cas d'une authentification à base de condensé que dans le cas d'une authentification basique. C'est pourquoi l'utilisation de l'authentification basique associée à un chiffrement de la connexion via mod_ssl constitue une bien meilleure alternative.

Traitement des bugs

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

Voir aussi

  • AuthName
  • AuthType
  • Require
  • Mode d'emploi de l'authentification

Utilisation de l'authentification à base de condensés

Pour utiliser l'authentification à base de condensés MD5, vous devez simplement remplacer AuthType Basic et AuthBasicProvider respectivement par AuthType Digest et AuthDigestProvider lorsque vous configurez l'authentification, puis ajouter une directive AuthDigestDomain contenant au moins la(les) URI(s) racine(s) de la zone à protéger.

On peut créer les fichiers utilisateur appropriés (au format texte) à l'aide de l'outil htdigest.

Exemple :

<Location "/private/">
    AuthType Digest
    AuthName "private area"
    AuthDigestDomain "/private/" "http://mirror.my.dom/private2/"

    AuthDigestProvider file
    AuthUserFile "/web/auth/.digest_pw"
    Require valid-user
</Location>

Note

L'authentification à base de condensé a été conçue pour améliorer la sécurité par rapport à l'authentification basique, mais il s'avère que ce but n'a pas été atteint. Un attaquant de type "man-in-the-middle" peut facilement forcer le navigateur à revenir à une authentification basique. Même une oreille indiscrète passive peut retrouver le mot de passe par force brute avec les moyens modernes, car l'algorithme de hashage utilisé par l'authentification à base de condensé est trop rapide. Autre problème, le stockage des mots de passe sur le serveur n'est pas sûr. Le contenu d'un fichier htdigest volé peut être utilisé directement pour l'authentification à base de condensé. Il est donc fortement recommandé d'utiliser mod_ssl pour chiffrer la connexion.

mod_auth_digest ne fonctionne correctement que sur les plates-formes où APR supporte la mémoire partagée.

Directive AuthDigestAlgorithm

Description: | Sélectionne l'algorithme utilisé pour calculer les condensés du défit et de sa réponse
Syntaxe: | AuthDigestAlgorithm MD5|MD5-sess
Défaut: | AuthDigestAlgorithm MD5
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_auth_digest

La directive AuthDigestAlgorithm permet de sélectionner l'algorithme utilisé pour calculer les condensés du défit et de sa réponse.

MD5-sess n'est pas encore correctement implémenté.

Directive AuthDigestDomain

Description: | Les URIs qui se trouvent dans le même espace de protection concernant l'authentification à base de condensés
Syntaxe: | AuthDigestDomain URI [URI] ...
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_auth_digest

La directive AuthDigestDomain vous permet de spécifier un ou plusieurs URIs se trouvant dans le même espace de protection (c'est à dire utilisant le même utilisateur/mot de passe et se trouvant dans le même domaine). Les URIs spécifiés sont des préfixes ; le client doit savoir que tous les URIs situés sous ces préfixes seront protégés par le même utilisateur/mot de passe. Les URIs peuvent être soit des URIs absolus (c'est à dire avec protocole, nom serveur, port, etc...), soit des URIs relatifs.

Cette directive doit toujours être présente et contenir au moins le(s) URI(s) racine(s) pour cet espace. Dans le cas contraire, le client va envoyer un en-tête d'autorisation avec chaque requête à destination de ce serveur.

Les URIs spécifiés peuvent aussi référencer différents serveurs, auquel cas les clients (qui sont à même de le comprendre) vont partager l'utilisateur/mot de passe entre plusieurs serveurs sans le demander à l'utilisateur à chaque fois.

Directive AuthDigestNonceLifetime

Description: | Durée de validité du nombre à valeur unique du serveur (nonce)
Syntaxe: | AuthDigestNonceLifetime secondes
Défaut: | AuthDigestNonceLifetime 300
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_auth_digest

La directive AuthDigestNonceLifetime permet de contrôler la durée de validité du nombre à valeur unique du serveur (nonce). Lorsque le client contacte le serveur en utilisant un nonce dont la validité a expiré, le serveur renvoie un code d'erreur 401 avec stale=true. Si secondes est supérieur à 0, il spécifie la durée de validité du nonce ; il est en général déconseillé d'affecter à cet argument une valeur inférieure à 10 secondes. Si secondes est inférieur à 0, le nonce n'expire jamais.

Directive AuthDigestProvider

Description: | Définit le(s) fournisseurs(s) d'authentification pour la zone du site web concernée
Syntaxe: | AuthDigestProvider nom fournisseur [nom fournisseur] ...
Défaut: | AuthDigestProvider file
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_auth_digest

La directive AuthDigestProvider permet de définir quel fournisseur d'authentification sera utilisé pour authentifier les utilisateurs pour la zone du site web concernée. Assurez-vous que le module implémentant le fournisseur d'authentification choisi soit bien présent dans le serveur. Le fournisseur par défaut file est implémenté par le module mod_authn_file.

Voir mod_authn_dbm, mod_authn_file, mod_authn_dbd et mod_authn_socache pour la liste des fournisseurs disponibles.

Directive AuthDigestQop

Description: | Détermine le niveau de protection fourni par l'authentification à base de condensé
Syntaxe: | AuthDigestQop none|auth|auth-int [auth|auth-int]
Défaut: | AuthDigestQop auth
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_auth_digest

La directive AuthDigestQop permet de définir le niveau de protection fourni. auth ne fournit que l'authentification (nom utilisateur/mot de passe) ; auth-int fournit l'authentification plus un contrôle d'intégrité (un condensé MD5 de l'entité est aussi calculé et vérifié) ; avec none, le module va utiliser l'ancien algorithme de condensés RFC-2069 (qui n'effectue pas de contrôle d'intégrité). On peut spécifier à la fois auth et auth-int, auquel cas c'est le navigateur qui va choisir lequel des deux utiliser. none ne doit être utilisé que dans le cas où le navigateur ne serait pas à même (pour une raison ou pour une autre) de relever le défit qu'il recevrait si un autre niveau de protection était défini.

auth-int n'est pas encore implémenté.

Directive AuthDigestShmemSize

Description: | La quantité de mémoire partagée à allouer afin de conserver les informations à propos des clients
Syntaxe: | AuthDigestShmemSize taille
Défaut: | AuthDigestShmemSize 1000
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_auth_digest

La directive AuthDigestShmemSize permet de définir la quantité de mémoire partagée à allouer au démarrage du serveur afin de conserver les informations à propos des clients. Notez que le segment de mémoire partagée ne peut pas être défini à une taille inférieure à l'espace nécessaire pour conserver les informations à propos d'un client. Cette valeur dépend de votre système. Si vous voulez en déterminer la valeur exacte, vous pouvez simplement définir AuthDigestShmemSize à 0 et consulter le message d'erreur que renverra le serveur lorsqu'on essaiera de le démarrer.

L'argument size s'exprime par défaut en octets, mais vous pouvez suffixer le nombre par un K ou un M pour spécifier respectivement des KiloOctets ou des MégaOctets. Par exemple, les directives qui suivent sont toutes équivalentes :

AuthDigestShmemSize 1048576
AuthDigestShmemSize 1024K
AuthDigestShmemSize 1M


mod_auth_form - Serveur Apache HTTP Version 2.4

Module Apache mod_auth_form

Description: | Authentification à l'aide d'un formulaire
Statut: | Base
Identificateur de Module: | auth_form_module
Fichier Source: | mod_auth_form.c
Compatibilité: | Disponible à partir d'Apache 2.3

Sommaire

Avertissement

L'authentification à base de formulaire dépend des modules mod_session qui utilisent les cookies HTTP, et en tant que tels s'exposent à des attaques de type Cross Site Scripting, ou risquent de divulguer des informations à caractère privé aux clients. Assurez-vous que ces risques ont bien été pris en compte avant d'activer les sessions sur votre serveur.

Ce module permet de restreindre l'accès en recherchant les utilisateurs dans les fournisseurs spécifiés à l'aide d'un formulaire de connexion HTML. Les formulaires HTML requièrent davantage de configuration que les méthodes d'authentification alternatives, mais ils peuvent s'avérer beaucoup plus conviviaux pour les utilisateurs.

L'authentification HTTP de base est fournie par le module mod_auth_basic, et l'authentification HTTP à base de condensé par le module mod_auth_digest. Le module mod_auth_form doit être utilisé avec au moins un module d'authentification du style mod_authn_file et un module d'autorisation comme mod_authz_user.

Lorsque l'utilisateur a été authentifié avec succès, ses informations de connexion sont stockés dans une session fournie par le module mod_session.

Traitement des bugs

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

Voir aussi

  • mod_session
  • AuthName
  • AuthType
  • Require
  • Mise en oeuvre de l'authentification

Configuration de base

Pour protéger une URL particulière avec le module mod_auth_form, vous devez déterminer l'endroit où vous allez stocker votre session, ainsi que la méthode d'authentification. Dans cet exemple simple, les informations de connexion sont stockées dans une session à l'aide du module mod_session_cookie, et l'authentification utilise un fichier en s'appuyant sur le module mod_authn_file. Si l'authentification échoue, l'utilisateur dera redirigé vers la page du formulaire de connexion.

Exemple simple

<Location "/admin">
    AuthFormProvider file
    AuthUserFile "conf/passwd"
    AuthType form
    AuthName "/admin"
    AuthFormLoginRequiredLocation "http://example.com/login.html"

    Session On
    SessionCookieName session path=/

    Require valid-user
</Location>

L'authentification mod_auth_form est activée en affectant la valeur form à la directive AuthType. Les directives AuthFormProvider et AuthUserFile spécifient que les noms d'utilisateurs et mots de passe seront vérifiés en utilisant le fichier choisi.

Les directives Session et SessionCookieName créent une session chiffrée stockée dans un cookie HTTP au niveau du navigateur. Pour plus d'informations à propos des différentes options de configuration des sessions, reportez-vous à la documentation du module mod_session.

Vous pouvez éventuellement ajouter une directive SessionCryptoPassphrase pour créer un cookie de session chiffré. Pour utiliser cette directive, le module mod_session_crypto doit avoir été préalablement chargé.

Dans l'exemple simple ci-dessus, une URL a été protégée par mod_auth_form, mais on doit maintenant fournir à l'utilisateur un moyen d'entrer un nom et un mot de passe. À cet effet, on peut soit écrire une page de connexion indépendante dédiée, soit inclure le formulaire de connexion dans la page courante.

Page de connexion dédiée

Le formulaire de connexion peut être contenu dans une page indépendante, ou être inclus dans la page courante.

Lorsque la connexion s'effectue à partir d'une page indépendante et si la tentative d'authentification échoue, l'utilisateur doit être redirigé vers un formulaire de connexion, créé à cet effet sur le site web, en utilisant la directive AuthFormLoginRequiredLocation. En général, la page de connexion contiendra un formulaire HTML demandant à l'utilisateur de fournir un nom et un mot de passe.

Exemple de formulaire de connexion

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

La partie où s'effectue la connexion proprement dite est traitée par le gestionnaire form-login-handler. L'action de ce formulaire doit pointer vers ce gestionnaire, ce que l'on configure dans Apache httpd comme suit :

Exemple de configuration du gestionnaire de formulaire de connexion

<Location "/dologin.html">
    SetHandler form-login-handler
    AuthFormLoginRequiredLocation "http://example.com/login.html"
    AuthFormLoginSuccessLocation "http://example.com/admin/index.html"
    AuthFormProvider file
    AuthUserFile "conf/passwd"
    AuthType form
    AuthName /admin
    Session On
    SessionCookieName session path=/
    SessionCryptoPassphrase secret
</Location>

L'URL spécifiée par la directive AuthFormLoginRequiredLocation référencera en général une page expliquant à l'utilisateur que sa tentative de connexion a échoué, et qu'il doit la renouveler. La directive AuthFormLoginSuccessLocation spécifie l'URL vers laquelle l'utilisateur doit être redirigé s'il s'est authentifié avec succès.

Alternativement, l'URL vers laquelle doit être redirigé l'utilisateur s'il s'est authentifié avec succès peut être intégrée dans le formulaire de connexion, comme dans l'exemple ci-dessous. Il en découle que le même gestionnaire form-login-handler pourra être utilisé pour différentes zones du site web.

Exemple de formulaire d'authentification multizone

<form method="POST" action="/dologin.html">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
  <input type="hidden" name="httpd_location" value="http://example.com/success.html" />
</form>

Connexion à la volée

Avertissement

Il existe un risque, dans certaines circonstances, que le formulaire de connexion configuré pour une connexion à la volée soit soumis plusieurs fois, révélant de ce fait les paramètres de connexion à l'application sous-jacente. L'administrateur doit s'assurer que cette dernière est correctement sécurisée afin d'éviter les éventuels abus. En cas de doute, utilisez une page de connexion indépendante dédiée.

Comme alternative à la page de connexion dédiée pour un site web, il est possible de configurer mod_auth_form pour authentifier les utilisateurs à la volée, sans les rediriger vers une autre page, ce qui permet de conserver l'état de la page courante au cours de la tentative de connexion. Ceci peut s'avérer utile dans le cas d'une session limitée dans le temps, si le délai de la session a expiré pendant la requête de l'utilisateur. Ce dernier peut alors se réauthentifier à la même place, et poursuivre son activité à partir du point où il en était resté.

Si un utilisateur non authentifié tente d'accéder à une page protégée par mod_auth_form, et si ce dernier n'est pas configuré avec une directive AuthFormLoginRequiredLocation, un code de statut HTTP_UNAUTHORIZED est renvoyé vers le navigateur, indiquant à l'utilisateur qu'il n'est pas autorisé à accéder à cette page.

Pour configurer l'authentification à la volée, l'administrateur remplace le message d'erreur renvoyé par le code de statut HTTP_UNAUTHORIZED par un message d'erreur personnalisé contenant le formulaire de connexion comme suit :

Exemple simple d'authentification à la volée

AuthFormProvider file
ErrorDocument 401 "/login.shtml"
AuthUserFile "conf/passwd"
AuthType form
AuthName realm
AuthFormLoginRequiredLocation "http://example.com/login.html"
Session On
SessionCookieName session path=/

La page du message d'erreur doit contenir un formulaire de connexion dont la propriété action est vide, comme dans l'exemple ci-dessous. Ceci a pour effet de soumettre le formulaire à l'URL protégée originale, cette dernière n'ayant pas besoin d'être connue de la page en cours.

Exemple de formulaire de connexion à la volée

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />
</form>

Lorsque l'utilisateur final a entré ses informations de connexion, le formulaire effectue une requête HTTP POST pour l'URL originale protégée par mot de passe. mod_auth_form va alors intercepter cette requête POST, et dans le cas où des champs HTML Utilisateur et Mot de passe corrects sont présents, l'utilisateur sera connecté, et l'URL originale protégée par mot de passe lui sera retournée en tant que requête GET.

Connexion à la volée avec conservation du contenu

Il existe une limite à la technique de connexion à la volée décrite ci-dessus ; si un formulaire HTML POST entraîne une demande d'authentification ou de réauthentification, le contenu du formulaire original envoyé par le navigateur sera perdu. Cela peut s'avérer plus ou moins gênant pour l'utilisateur final selon la fonction du site web.

Comme solution à ce problème, mod_auth_form permet d'intégrer la méthode et le contenu de la requête originale dans le formulaire de connexion. Si l'authentification réussit, Apache httpd pourra refaire une tentative avec la méthode et le contenu originaux, tout en conservant l'état de la requête originale.

Pour mettre en oeuvre la conservation du contenu, vous devez ajouter trois champs supplémentaires au formulaire de connexion comme dans l'exemple suivant :

Exemple de formulaire avec conservation du contenu

<form method="POST" action="">
  Username: <input type="text" name="httpd_username" value="" />
  Password: <input type="password" name="httpd_password" value="" />
  <input type="submit" name="login" value="Login" />

  <input type="hidden" name="httpd_method" value="POST" />
  <input type="hidden" name="httpd_mimetype" value="application/x-www-form-urlencoded" />
  <input type="hidden" name="httpd_body" value="name1=value1&name2=value2" />

</form>

La manière dont la méthode, le type MIME et le contenu de la requête originale seront intégrés dans le formulaire de connexion vont dépendre de la plate-forme et de la technologie utilisées au sein du site web.

Une option consiste à utiliser le module mod_include en association avec la directive KeptBodySize, ainsi qu'un script CGI adapté pour intégrer les variables dans le formulaire.

Une autre option consiste à présenter le formulaire de connexion en utilisant un script CGI ou une autre technologie dynamique.

Exemple avec script CGI

        AuthFormProvider file
        ErrorDocument 401 "/cgi-bin/login.cgi"
        ...

Déconnexion

Pour permettre à un utilisateur de se déconnecter d'une session particulière, vous devez configurer une page pour qu'elle soit traitée par le gestionnaire form-logout-handler. Tout accès à cette URL va entraîner la suppression de l'Utilisateur et du Mot de passe de la session courante, ce qui aura pour effet de déconnecter l'utilisateur.

Vous pouvez spécifier une URL vers laquelle le navigateur sera redirigé en cas de déconnection réussie, en définissant la directive AuthFormLogoutLocation. Cette URL devra expliquer à l'utilisateur qu'il a été déconnecté, et lui donner la possibilité de se connecter à nouveau.

Exemple simple de configuration de la déconnexion

SetHandler form-logout-handler
AuthName realm
AuthFormLogoutLocation "http://example.com/loggedout.html"
Session On
SessionCookieName session path=/

Notez que la déconnexion d'un utilisateur ne supprime pas la session ; elle supprime seulement l'utilisateur et le mot de passe de la session. Si la session qui en résulte est vide, elle sera probablement supprimée, mais ce n'est pas garanti. Si vous voulez être sûr que la session sera supprimée, affectez une valeur faible à la directive SessionMaxAge, par exemple 1 (affecter à cette directive la valeur zéro signifie une session sans limite d'âge).

Exemple simple avec durée de validité de session limitée

SetHandler form-logout-handler
AuthFormLogoutLocation "http://example.com/loggedout.html"
Session On
SessionMaxAge 1
SessionCookieName session path=/

Noms d'utilisateurs et mots de passe

Notez que la soumission d'un formulaire implique l'encodage URL (URLEncoding) des données du formulaire, ici le nom d'utilisateur et le mot de passe. Vous devez donc choisir des noms d'utilisateurs et mots de passe qui ne contiennent pas de caractères susceptibles d'être encodés URL lors de la soumission du formulaire, sous peine d'obtenir des résultats inattendus.

Directive AuthFormAuthoritative

Description: | Détermine si l'autorisation et l'authentification sont confiés à des modules de plus bas niveau
Syntaxe: | AuthFormAuthoritative On|Off
Défaut: | AuthFormAuthoritative On
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_auth_form

Normalement, chacun des modules d'autorisation spécifiés par la directive AuthFormProvider va tenter de vérifier l'identité de l'utilisateur, et si ce dernier n'est trouvé dans aucun fournisseur, l'accès sera refusé. En définissant explicitement la directive AuthFormAuthoritative à Off on confie les processus d'authentification et d'autorisation à des modules ne s'appuyant pas sur des fournisseurs, si aucun identifiant utilisateur ou aucune règle ne correspond à l'identifiant utilisateur fourni. Ceci ne peut s'avérer nécessaire que si l'on combine mod_auth_form avec des modules tiers qui ne se configurent pas avec la directive AuthFormProvider. Lorsqu'on utilise de tels modules, la chronologie du processus est déterminée dans leur code source, et n'est pas configurable.

Directive AuthFormBody

Description: | Le nom du champ de formulaire contenant le corps de la requête à effectuer en cas de connexion réussie
Syntaxe: | AuthFormBody nom du champ
Défaut: | httpd_body
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormBody spécifie le nom du champ HTML qui, s'il existe, contiendra le corps de la requête à effectuer en cas de connexion réussie.

En ajoutant au formulaire les champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, un site web sera en mesure de relancer une requête qui a été éventuellement interrompue par l'écran de connexion, ou par l'expiration d'un délai de session.

Directive AuthFormDisableNoStore

Description: | Désactive l'en-tête CacheControl no-store sur la page de connexion
Syntaxe: | AuthFormDisableNoStore On|Off
Défaut: | AuthFormDisableNoStore Off
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

Le drapeau AuthFormDisableNoStore supprime l'envoi d'un en-tête Cache-Control no-store lorsqu'une page avec code d'erreur 401 est renvoyée, si l'utilisateur n'est pas encore connecté. Avec cette en-tête, il est plus difficile pour une application ecmascript de resoumettre un formulaire de connexion, et ainsi révéler le nom d'utilisateur et le mot de passe à l'application sous-jacente. Vous devez être conscient des risques encourus si vous le désactivez.

Directive AuthFormFakeBasicAuth

Description: | Simule une en-tête d'authentification de base
Syntaxe: | AuthFormFakeBasicAuth On|Off
Défaut: | AuthFormFakeBasicAuth Off
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

Le drapeau AuthFormFakeBasicAuth détermine si une en-tête d'Authentification de base sera ajoutée aux en-têtes de la requête. On peut utiliser cette méthode pour présenter le nom d'utilisateur et le mot de passe à l'application sous-jacente, sans que cette dernière ait besoin de connaître la manière dont le processus de connexion a été mené à bien.

Directive AuthFormLocation

Description: | Le nom du champ de formulaire qui contiendra l'URL vers laquelle l'utilisateur sera redirigé en cas de connexion réussie
Syntaxe: | AuthFormLocation nom du champ
Défaut: | httpd_location
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormLocation spécifie le nom du champ HTML qui, s'il existe, contiendra l'URL vers laquelle rediriger le navigateur en cas de connexion réussie.

Directive AuthFormLoginRequiredLocation

Description: | L'URL de la page vers laquelle on doit être redirigé si une authentification est requise
Syntaxe: | AuthFormLoginRequiredLocation url
Défaut: | none
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache. L'interprétation des expressions rationnelles est supportée depuis la version 2.4.4.

La directive AuthFormLoginRequiredLocation spécifie l'URL vers laquelle l'utilisateur devra être redirigé s'il n'est pas autorisé à accéder à une page. Sa valeur est interprétée via l'interpréteur ap_expr avant d'être envoyée au client. Par défaut, si un utilisateur n'est pas autorisé à accéder à une page, le code de réponse HTTP HTTP_UNAUTHORIZED est renvoyé avec la page spécifiée par la directive ErrorDocument. La directive AuthFormLoginRequiredLocation permet de remplacer cette valeur par défaut.

Vous pouvez utiliser cette directive si vous voulez présenter une page de connexion personnalisée à vos utilisateurs.

Directive AuthFormLoginSuccessLocation

Description: | L'URL de la page vers laquelle on doit être redirigé en cas de connexion réussie
Syntaxe: | AuthFormLoginSuccessLocation url
Défaut: | none
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache. L'interprétation des expressions rationnelles est supportée depuis la version 2.4.4.

La directive AuthFormLoginSuccessLocation spécifie l'URL vers laquelle l'utilisateur doit être redirigé en cas de connexion réussie. Sa valeur est interprétée via l'interpréteur ap_expr avant d'être envoyée au client. L'effet de cette directive peut être annulé si l'on a défini un champ de formulaire contenant une autre URL à l'aide de la directive AuthFormLocation.

Vous pouvez utiliser cette directive si vous possédez une URL de connexion personnalisée, et si vous n'avez pas intégré la page de destination dans le formulaire de connexion.

Directive AuthFormLogoutLocation

Description: | L'URL vers laquelle un utilisateur devra être redirigé après s'être déconnecté
Syntaxe: | AuthFormLogoutLocation uri
Défaut: | none
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache. L'interprétation des expressions rationnelles est supportée depuis la version 2.4.4.

La directive AuthFormLogoutLocation spécifie l'URL de la page du serveur vers laquelle l'utilisateur devra être redirigé s'il se déconnecte. Sa valeur est interprétée via l'interpréteur ap_expr avant d'être envoyée au client.

Lorsqu'un accès est tenté sur un URI traité par le gestionnaire form-logout-handler, la page spécifiée par cette directive sera présentée à l'utilisateur final. Par exemple :

Exemple

<Location "/logout">
    SetHandler form-logout-handler
    AuthFormLogoutLocation "http://example.com/loggedout.html"
    Session on
    #...
</Location>

Si un utilisateur tente d'accéder à l'URI /logout/, il sera déconnecté, et la page /loggedout.html lui sera présentée. Assurez-vous que la page loggedout.html n'est pas protégée par mot de passe, car dans le cas contraire, elle ne serait pas affichée.

Directive AuthFormMethod

Description: | Le nom du champ de formulaire contenant la méthode de la requête à effectuer en cas de connexion réussie
Syntaxe: | AuthFormMethod nom du champ
Défaut: | httpd_method
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormMethod spécifie le nom du champ HTML qui, s'il existe, contiendra le type MIME de la requête à effectuer en cas de connexion réussie.

En ajoutant au formulaire les champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, un site web sera en mesure de relancer une requête qui a été éventuellement interrompue par l'écran de connexion, ou par l'expiration d'un délai de session.

Directive AuthFormMimetype

Description: | Le nom du champ de formulaire contenant le type MIME du corps de la requête à effectuer en cas de connexion réussie
Syntaxe: | AuthFormMimetype nom du champ
Défaut: | httpd_mimetype
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormMimetype spécifie le nom du champ HTML qui, s'il existe, contiendra le type MIME de la requête à effectuer en cas de connexion réussie.

En ajoutant au formulaire les champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, un site web sera en mesure de relancer une requête qui a été éventuellement interrompue par l'écran de connexion, ou par l'expiration d'un délai de session.

Directive AuthFormPassword

Description: | Le nom du champ de formulaire qui contient le mot de passe de connexion
Syntaxe: | AuthFormPassword nom du champ
Défaut: | httpd_password
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormPassword permet de spécifier le nom du champ HTML qui, s'il existe, contiendra le mot de passe qui sera utilisé pour la connexion.

Directive AuthFormProvider

Description: | Définit le(s) fournisseur(s) d'authentification pour la zone concernée
Syntaxe: | AuthFormProvider nom fournisseur [nom fournisseur] ...
Défaut: | AuthFormProvider file
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_auth_form

La directive AuthFormProvider permet de définir quel fournisseur sera utilisé pour authentifier les utilisateurs pour la zone concernée. Le fournisseur par défaut file est implémenté par le module mod_authn_file. Assurez-vous que le fournisseur choisi soit bien présent dans le serveur.

Exemple

<Location "/secure">
    AuthType form
    AuthName "private area"
    AuthFormProvider  dbm
    AuthDBMType        SDBM
    AuthDBMUserFile    "/www/etc/dbmpasswd"
    Require            valid-user
    #...
</Location>

Les différents fournisseurs sont implémentés par les modules mod_authn_dbm, mod_authn_file, mod_authn_dbd et mod_authnz_ldap.

Directive AuthFormSitePassphrase

Description: | Court-circuite l'authentification pour les sites à fort trafic
Syntaxe: | AuthFormSitePassphrase secret
Défaut: | none
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormSitePassphrase spécifie un mot de passe qui, s'il est présent dans la session utilisateur, indique à Apache httpd de court-circuiter l'authentification pour l'URL considérée. On peut l'utiliser dans le cas de sites web à fort trafic afin de réduire la charge induite sur l'infrastructure d'authentification.

On peut insérer le mot de passe dans une session utilisateur en ajoutant cette directive à la configuration concernant le gestionnaire form-login-handler. Le gestionnaire form-login-handler, quant à lui, effectuera toujours les vérifications d'authentification, qu'un mot de passe soit spécifié ou non.

Avertissement

Si la session est présentée à l'utilisateur à l'aide du module mod_session_cookie, et si la session n'est pas protégée par le module mod_session_crypto, le mot de passe peut faire l'objet d'une attaque de type dictionnaire. Quelle que soit la configuration de la session, assurez-vous que cette directive n'est pas utilisée dans un espace d'URLs contenant des données privées, ou à partir desquelles des transactions sensibles pourraient être menées. En tout état de cause, vous devez être conscient des risques encourus avant de l'utiliser.

Directive AuthFormSize

Description: | La taille maximale en octets du formulaire dont seront extraites les informations de connexion
Syntaxe: | AuthFormSize taille
Défaut: | 8192
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive AuthFormSize spécifie la taille maximale du corps de la requête qui sera utilisée pour trouver le formulaire de connexion.

Si une requête de connexion entrante possède une taille supérieure à cette valeur, elle sera rejetée avec le code de réponse HTTP HTTP_REQUEST_TOO_LARGE.

Si vous avez ajouté au formulaire des champs décrits dans AuthFormMethod, AuthFormMimetype et AuthFormBody, il est recommandé de définir cette directive à une valeur similaire à celle de la directive KeptBodySize.

Directive AuthFormUsername

Description: | Le nom du champ de formulaire qui contient le nom de connexion
Syntaxe: | AuthFormUsername nom du champ
Défaut: | httpd_username
Contexte: | répertoire
Statut: | Base
Module: | mod_auth_form
Compatibilité: | Disponible depuis la version 2.3.3 du serveur HTTP Apache

La directive AuthFormUsername permet de spécifier le nom du champ HTML qui, s'il existe, contiendra le nom d'utilisateur qui sera utilisé pour la connexion.


mod_authn_anon - Serveur Apache HTTP Version 2.4

Module Apache mod_authn_anon

Description: | Permet un accès "anonyme" à des zones protégées
Statut: | Extension
Identificateur de Module: | authn_anon_module
Fichier Source: | mod_authn_anon.c
Compatibilité: | Disponible depuis la version 2.1 d'Apache

Sommaire

Ce module permet aux frontaux d'authentification comme mod_auth_basic d'authentifier les utilisateurs à la manière des sites FTP anonymes, c'est à dire en fournissant l'identifiant utilisateur spécial 'anonymous' et l'adresse email comme mot de passe. Ces adresses email peuvent être journalisées.

En combinaison avec d'autres méthodes de contrôle d'accès (base de données), ce module permet d'effectuer un véritable suivi des utilisateurs et une personnalisation de leurs accès en fonction de leur profil, tout en conservant l'accessibilité du site aux utilisateurs 'non enregistrés'. Un avantage du suivi des utilisateurs basé sur l'authentification réside dans le fait qu'il est, à l'opposé des cookies magiques et des drôles d'URLs avec préfixes ou suffixes, entièrement indépendant du navigateur et qu'il permet de partager des URLs entre plusieurs utilisateurs.

Si l'on utilise le module mod_auth_basic, le module mod_authn_anon est invoqué en affectant la valeur anon à la directive AuthBasicProvider.

Exemple

L'exemple ci-dessous présente un exemple de combinaison avec l'authentification à base de fichier htpasswd "normale", et permet la connexion d'utilisateurs en tant qu'invités avec les propriétés suivantes :

  • Il incite l'utilisateur à fournir un identifiant. (Anonymous_NoUserID)
  • Il incite l'utilisateur à fournir un mot de passe. (Anonymous_MustGiveEmail)
  • Le mot de passe fourni doit être une adresse email valide, c'est à dire contenant au moins un '@' et un '.'. (Anonymous_VerifyEmail)
  • Les valeurs possibles pour l'identifiant utilisateur sont anonymous, guest, www, test ou welcome, et la vérification n'est pas sensible à la casse. (Anonymous)
  • Les adresses email entrées dans le champ passwd sont enregistrées dans le fichier journal des erreurs. (Anonymous_LogEmail)

Exemple

<Directory "/var/www/html/private">
    AuthName "Use 'anonymous' & Email address for guest entry"
    AuthType Basic
    AuthBasicProvider file anon
    AuthUserFile "/path/to/your/.htpasswd"

    Anonymous_NoUserID off
    Anonymous_MustGiveEmail on
    Anonymous_VerifyEmail on
    Anonymous_LogEmail on
    Anonymous anonymous guest www test welcome

    Require valid-user
</Directory>

Directive Anonymous

Description: | Définit la liste des identifiants utilisateur autorisés à accéder sans vérification du mot de passe
Syntaxe: | Anonymous utilisateur [utilisateur] ...
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authn_anon

Une liste d'un ou plusieurs identifiants utilisateur spéciaux autorisés à accéder sans vérification du mot de passe. Les identifiants doivent être séparés par un espace. Pour spécifier un identifiant contenant un espace, on peut utiliser les guillemets ' ou ", ou le caractère d'échappement \.

Veuillez noter que la vérification n'est pas sensible à la casse.
Il est fortement conseillé d'intégrer l'utilisateur spécial 'anonymous' dans la liste des identifiants.

Exemple:

Anonymous anonymous "Not Registered" "I don't know"

Dans cet exemple, l'utilisateur peut accéder au site sans vérification du mot de passe en utilisant l'identifiant "anonymous", "Not Registered", "I Don't Know" ou encore "AnonyMous".

Depuis Apache 2.1, il est possible de remplacer la liste des identifiants autorisés par le caractère "*", ce qui permet d'utiliser n'importe quel identifiant pour pouvoir accéder au site.

Directive Anonymous_LogEmail

Description: | Détermine si le mot de passe fourni sera enregistré dans le journal des erreurs
Syntaxe: | Anonymous_LogEmail On|Off
Défaut: | Anonymous_LogEmail On
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authn_anon

Lorsque cette directive est définie à On, valeur par défaut, le 'mot de passe' fourni (censé contenir une adresse email valide) est enregistré dans le journal des erreurs.

Directive Anonymous_MustGiveEmail

Description: | Détermine si l'abscence de mot de passe est autorisée
Syntaxe: | Anonymous_MustGiveEmail On|Off
Défaut: | Anonymous_MustGiveEmail On
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authn_anon

Détermine si l'utilisateur doit spécifier une adresse email comme mot de passe. Lorsque cette directive est définie à On, l'abscence de mot de passe est interdite.

Directive Anonymous_NoUserID

Description: | Détermine si le champ identifiant peut être vide
Syntaxe: | Anonymous_NoUserID On|Off
Défaut: | Anonymous_NoUserID Off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authn_anon

Lorsque cette directive est définie à On, les utilisateurs peuvent laisser le champ identifiant vide (et peut-être aussi le champ mot de passe selon la définition de la directive Anonymous_MustGiveEmail). Ceci peut s'avérer très utile pour les utilisateurs de MS-Explorer qui n'ont pour seule possibilité que d'appuyer sur Entrée ou de cliquer directement sur le bouton OK, ce qui semble être une réaction naturelle.

Directive Anonymous_VerifyEmail

Description: | Détermine s'il faut vérifier que le format de l'adresse email fournie comme mot de passe est correct
Syntaxe: | Anonymous_VerifyEmail On|Off
Défaut: | Anonymous_VerifyEmail Off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authn_anon

Lorsque cette directive est définie à On, Apache vérifie que le 'mot de passe' entré contient au moins un '@' et un '.' afin d'inciter les utilisateurs à fournir des adresses email valides (voir ci-dessus la directive Anonymous_LogEmail).


mod_authn_core - Serveur Apache HTTP Version 2.4

Module Apache mod_authn_core

Description: | Le noyau de l'authentification
Statut: | Base
Identificateur de Module: | authn_core_module
Fichier Source: | mod_authn_core.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

Ce module fournit le coeur des fonctionnalités d'authentification permettant d'accorder ou de refuser l'accès à certaines zones du site web. Les directives fournies par le module mod_authn_core sont communes à tous les fournisseurs d'authentification.

Création d'alias de fournisseurs d'authentification

Il est possible de créer des fournisseurs d'authentification étendus dans le fichier de configuration et de leur assigner un alias. Le fournisseur ainsi nommé peut alors être référencé à l'aide des directives AuthBasicProvider ou AuthDigestProvider tout comme un fournisseur d'authentification de base. Outre la possibilité de créer et attribuer un alias à un fournisseur étendu, le même fournisseur d'authentification peut aussi être référencé par plusieurs sections relatives à une zone du site web.

Exemples

Cet exemple vérifie les mots de passe dans deux fichiers textes différents.

Vérification dans plusieurs fichiers de mots de passe au format texte

# Première vérification
<AuthnProviderAlias file file1>
    AuthUserFile "/www/conf/passwords1"
</AuthnProviderAlias>

# Vérification suivante
<AuthnProviderAlias file file2>
    AuthUserFile "/www/conf/passwords2"
</AuthnProviderAlias>

<Directory "/var/web/pages/secure">
    AuthBasicProvider file1 file2

    AuthType Basic
    AuthName "Protected Area"
    Require valid-user
</Directory>

Dans l'exemple ci-dessous, deux fournisseurs d'authentification ldap sont créés à partir du fournisseur ldap de base, et se voient attribuer un alias. L'authentification d'une même zone peut alors être traitée par plusieurs serveurs ldap :

Vérification auprès de plusieurs serveurs LDAP

<AuthnProviderAlias ldap ldap-alias1>
    AuthLDAPBindDN cn=youruser,o=ctx
    AuthLDAPBindPassword yourpassword
    AuthLDAPURL ldap://ldap.host/o=ctx
    </AuthnProviderAlias>
    <AuthnProviderAlias ldap ldap-other-alias>
    AuthLDAPBindDN cn=yourotheruser,o=dev
    AuthLDAPBindPassword yourotherpassword
    AuthLDAPURL ldap://other.ldap.host/o=dev?cn
</AuthnProviderAlias>

Alias "/secure" "/webpages/secure"
<Directory "/webpages/secure">

    AuthBasicProvider ldap-other-alias  ldap-alias1

    AuthType Basic
    AuthName LDAP_Protected Place
    Require valid-user
    # Notez que Require ldap-* ne fonctionnerait pas ici, car
    # AuthnProviderAlias ne fournit pas de configuration pour les
    # fournisseurs d'autorisation implémentés dans le même module que le
    # fournisseur d'authentification.
</Directory>

Directive AuthName

Description: | L'identifiant de l'autorisation à utiliser avec l'authentification HTTP
Syntaxe: | AuthName domaine d'autorisation
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authn_core

Cette directive permet de définir l'identifiant d'autorisation pour un répertoire. Cet identifiant est fourni au client de façon à ce qu'il sache quels nom d'utilisateur et mot de passe envoyer. AuthName accepte un seul argument ; s'il contient des espaces, il doit être entouré de guillemets. Pour pouvoir fonctionner, la directive AuthName doit être utilisée en combinaison avec les directives AuthType et Require, ainsi que des directives comme AuthUserFile et AuthGroupFile.

Par exemple :

AuthName "Top Secret"

La chaîne fournie comme argument à AuthName apparaîtra dans la boîte de dialogue d'authentification pour la plupart des navigateurs.

Voir aussi

  • Authentification, autorisation et contrôle d'accès
  • mod_authz_core

Directive <AuthnProviderAlias>

Description: | Regroupe un ensemble de directives qui constituent une extension d'un fournisseur d'authentification de base et lui attribue l'alias spécifié
Syntaxe: | <AuthnProviderAlias alias-fournisseur> ... </AuthnProviderAlias>
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_authn_core

Les balises <AuthnProviderAlias> et </AuthnProviderAlias> permettent de regrouper un ensemble de directives d'authentification qui seront référencées par l'alias spécifié à l'aide des directives AuthBasicProvider ou AuthDigestProvider.

Cette directive n'a aucun influence sur le processus d'autorisation, même pour les modules qui fournissent à la fois l'authentification et l'autorisation.

Directive AuthType

Description: | Type d'authentification utilisateur
Syntaxe: | AuthType None|Basic|Digest|Form
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authn_core

Cette directive permet de définir le type d'authentification utilisateur pour un répertoire. Les types d'authentification disponibles sont None, Basic (implémenté par mod_auth_basic), Digest (implémenté par mod_auth_digest), et Form (implémenté par mod_auth_form).

Pour mettre en oeuvre l'authentification, vous devez aussi utiliser les directives AuthName et Require. De plus, le serveur doit pouvoir disposer d'un module fournisseur d'authentification comme mod_authn_file et d'un module d'autorisation comme mod_authz_user.

Le type d'authentification None désactive l'authentification. Lorsqu'une authentification est définie, elle est en général héritée par chacune des sections de configuration qui suivent, à moins qu'un autre type d'authentification ne soit spécifié. Si l'on ne souhaite pas mettre en oeuvre d'authentification pour une sous-section d'une section authentifiée, on doit utiliser le type d'authentification None ; dans l'exemple suivant, les clients peuvent accéder au répertoire /www/docs/public sans devoir s'authentifier :

<Directory "/www/docs">
    AuthType Basic
    AuthName Documents
    AuthBasicProvider file
    AuthUserFile "/usr/local/apache/passwd/passwords"
    Require valid-user
</Directory>

<Directory "/www/docs/public">
    AuthType None
    Require all granted
</Directory>
Veuillez noter que, lorsque l'authentification n'est pas activée, les clients qui se sont déjà authentifiés pour une autre zone de l'arborescence du site continueront en général à envoyer des en-tête d'authentification HTTP ou des cookies avec chaque requête, sans se préoccuper de savoir si le serveur nécessite vraiment une authentification pour chaque ressource.

Voir aussi

  • Authentification, autorisation et contrôle d'accès


mod_authn_dbd - Serveur Apache HTTP Version 2.4

Module Apache mod_authn_dbd

Description: | Authentification utilisateur à l'aide d'une base de données SQL
Statut: | Extension
Identificateur de Module: | authn_dbd_module
Fichier Source: | mod_authn_dbd.c
Compatibilité: | Disponible depuis la version 2.1 d'Apache

Sommaire

Ce module permet aux frontaux d'authentification comme mod_auth_digest et mod_auth_basic d'authentifier les utilisateurs en les recherchant dans une base de données SQL. mod_authn_file, par exemple, fournit une fonctionnalité similaire.

Ce module s'appuie sur mod_dbd pour spécifier le pilote de la base de données sous-jacente et les paramètres de connexion, mais aussi pour gérer les connexions à la base de données.

Si l'on utilise mod_auth_basic ou mod_auth_digest, on peut invoquer ce module en affectant la valeur dbd à la directive AuthBasicProvider ou AuthDigestProvider.

Traitement des bugs

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

Voir aussi

  • AuthName
  • AuthType
  • AuthBasicProvider
  • AuthDigestProvider
  • DBDriver
  • DBDParams
  • Formats de mots de passe

Performances et mise en cache

Certains utilisateurs de l'authentification DBD sous HTTPD 2.2/2.4 ont signalé une charge problématique au niveau de la base de données. Cela se produit en général lorsqu'une page HTML contient des centaines d'objets (comme des images, des scripts, etc...), chacun d'entre eux nécessitant une authentification. Les utilisateurs qui rencontrent ce genre de problème peuvent utiliser le module mod_authn_socache qui permet de mettre les données d'authentification en cache, et soulager ainsi la base de données de la plus grande partie de la charge.

Exemple de configuration

Voici un exemple simple d'utilisation de ce module dans un contexte d'authentification et de bases de données.

# configuration de mod_dbd
# MISE À JOUR pour inclure la mise en cache de l'authentification
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache password=xxxxxx"

DBDMin  4
DBDKeep 8
DBDMax  20
DBDExptime 300

<Directory "/usr/www/mon-serveur/private">
  # configuration de mod_authn_core et mod_auth_basic
  # pour mod_authn_dbd
  AuthType Basic
  AuthName "Mon serveur"

  # Pour mettre en cache les données d'authentification, placez socache
  # avant dbd
  AuthBasicProvider socache dbd

  # Aussi nécessaire à la mise en cache : dire au cache de mettre en
  # cache les recherches dbd !
  AuthnCacheProvideFor dbd
  AuthnCacheContext mon-serveur

  # configuration de mod_authz_core
  Require valid-user

  # la requête SQL de mod_authn_dbd pour authentifier un utilisateur
  AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
</Directory>

Mise à disposition des informations de connexion

Si httpd a été compilé avec la version 1.3.0 ou supérieure de l'APR, pour chaque requête envoyée au serveur de base de données, toutes les valeurs de colonnes du premier enregistrement renvoyé par la requête sont affectées à des variables d'environnement avec le préfixe "AUTHENTICATE_".

Par exemple, si une requête renvoie un nom d'utilisateur, un nom complet et un numéro de téléphone, un programme CGI pourra accéder à ces informations sans avoir besoin d'effectuer une deuxième requête vers la base de données.

Ceci va entraîner une simplification considérable du code et de la configuration nécessaire de certaines applications web.

Directive AuthDBDUserPWQuery

Description: | Requête SQL servant à vérifier le mot de passe d'un utilisateur
Syntaxe: | AuthDBDUserPWQuery requête
Contexte: | répertoire
Statut: | Extension
Module: | mod_authn_dbd

La directive AuthDBDUserPWQuery permet de spécifier une requête servant à vérifier le mot de passe d'un utilisateur donné. L'identifiant utilisateur sera transmis comme paramètre sous forme d'une seule chaîne de caractères lorsque la requête sera exécutée. Cet identifiant est référencé dans la requête en utilisant le spécificateur de format %s.

AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"

La première colonne du premier enregistrement renvoyé par la requête se présentera sous la forme d'une chaîne de caractères contenant le mot de passe chiffré. Les enregistrements suivants sont ignorés. Si aucun enregistrement n'est renvoyé, l'utilisateur ne sera pas authentifié par mod_authn_dbd.

Si httpd a été compilé avec la version 1.3.0 ou supérieure de l'APR, toute valeur de colonne supplémentaire du premier enregistrement renvoyé par la requête sera stockée dans une variable d'environnement dont le nom aura la forme AUTHENTICATE_valeur-colonne.

Le format du mot de passe chiffré dépend du frontal d'authentification utilisé (par exemple mod_auth_basic ou mod_auth_digest). Voir la documentation sur les Formats de mots de passe pour plus de détails.

Directive AuthDBDUserRealmQuery

Description: | Requête SQL servant à vérifier une empreinte de mot de passe pour un utilisateur et un identifiant d'authentification.
Syntaxe: | AuthDBDUserRealmQuery requête
Contexte: | répertoire
Statut: | Extension
Module: | mod_authn_dbd

La directive AuthDBDUserRealmQuery permet de spécifier une requête SQL servant à vérifier une empreinte de mot de passe pour un utilisateur et un identifiant d'authentification donnés au cours d'un processus d'authentification digest. Les identifiants de l'utilisateur et de l'authentification sont passés dans cet ordre comme paramètres à l'exécution de la requête. Ils sont référencés dans la chaîne de la requête en utilisant des spécificateurs de format %s.

AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s"

La première colonne du premier enregistrement renvoyé par la requête se présentera sous la forme d'une chaîne de caractères contenant le mot de passe chiffré. Les enregistrements suivants seront ignorés. Si aucun enregistrement n'est renvoyé, l'utilisateur ne sera pas authentifié par mod_authn_dbd.

Si httpd a été compilé avec une version 1.3.0 ou supérieure de l'APR, toute valeur de colonne supplémentaire du premier enregistrement renvoyé par la requête sera stockée dans une variable d'environnement avec un nom de la forme AUTHENTICATE_COLONNE.

Le format du mot de passe chiffré dépend du frontal d'authentification utilisé (par exemple mod_auth_basic ou mod_auth_digest). Voir la documentation sur les Formats de mots de passe pour plus de détails.


mod_authn_dbm - Serveur Apache HTTP Version 2.4

Module Apache mod_authn_dbm

Description: | Authentification utilisateur utilisant des fichiers DBM
Statut: | Extension
Identificateur de Module: | authn_dbm_module
Fichier Source: | mod_authn_dbm.c
Compatibilité: | Disponible depuis les versions 2.1 et supérieures d'Apache

Sommaire

Ce module permet aux frontaux comme mod_auth_digest et mod_auth_basic d'authentifier les utilisateurs en les recherchant dans des fichiers de mots de passe dbm. mod_authn_file fournit une fonctionnalité similaire.

Lorsqu'on utilise mod_auth_basic ou mod_auth_digest, ce module est invoqué en affectant la valeur dbm à la directive AuthBasicProvider ou AuthDigestProvider.

Traitement des bugs

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

Voir aussi

  • AuthName
  • AuthType
  • AuthBasicProvider
  • AuthDigestProvider
  • htpasswd
  • htdbm
  • Formats de mots de passe

Directive AuthDBMType

Description: | Définit le type de fichier de base de données utilisé pour stocker les mots de passe
Syntaxe: | AuthDBMType default|SDBM|GDBM|NDBM|DB
Défaut: | AuthDBMType default
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authn_dbm

Cette directive permet de définir le type de fichier de base de données utilisé pour stocker les mots de passe. Le type de base de données par défaut est défini à la compilation. La liste des autres types de bases de données disponibles dépend aussi de la configuration de la compilation.

Par exemple, pour activer le support de Berkeley DB (correspondant au type db), il faut ajouter l'option --with-berkeley-db à la ligne de commande configure de httpd pour générer le DSO approprié.

Il est impératif que le programme que vous utilisez pour créer vos fichiers de mots de passe soit configuré pour utiliser le même type de base de données.

Directive AuthDBMUserFile

Description: | Définit le nom d'un fichier de base de données pour l'authentification contenant la liste des utilisateurs et de leurs mots de passe
Syntaxe: | AuthDBMUserFile chemin-fichier
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authn_dbm

La directive AuthDBMUserFile permet de définir le nom d'un fichier de base de données pour l'authentification contenant la liste des utilisateurs et de leurs mots de passe. chemin-fichier doit être un chemin absolu vers le fichier de base de données.

La clé du fichier de base de données est le nom de l'utilisateur. La valeur associée est le mot de passe chiffré, éventuellement suivi par un ':' et des données arbitraires. Ce ':' ainsi que les données arbitraires qui suivent seront ignorées par le serveur.

Sécurité :

Faites en sorte que le fichier spécifié par la directive AuthDBMUserFile soit stocké en dehors de l'arborescence des documents du serveur web ; en particulier, ne l'enregistrez pas dans le répertoire qu'il protège, faute de quoi, les clients auraient la possibilité de télécharger le fichier des mots de passe.

Le format de mot de passe chiffré dépend du frontal d'authentification utilisé (par exemple mod_auth_basic ou mod_auth_digest). Voir la documentation sur les Formats de mots de passe pour plus de détails.

Note importante concernant la compatibilité : l'implémentation de dbmopen dans les modules d'Apache lit la longueur de la chaîne correspondant aux données chiffrées dans la structure des données DBM, plutôt que de calculer cette longueur en se basant sur le caractère nul final. Certaines applications par contre, comme le serveur web Netscape, calculent cette longueur en se basant sur le caractère nul final ; par conséquent, si vous rencontrez des difficultés en échangeant des fichiers DBM entre plusieurs applications, le problème peut éventuellement s'expliquer par cette différence d'implémentation.

Un script perl nommé dbmmanage est fourni avec Apache. On peut utiliser ce programme pour créer et mettre à jour les fichiers de mots de passe au format DBM que ce module utilise. Il existe également un autre outil pour gérer les fichiers DBM, inclus dans le programme htdbm.


mod_authn_file - Serveur Apache HTTP Version 2.4

Module Apache mod_authn_file

Description: | Authentification utilisateur à l'aide de fichiers texte
Statut: | Base
Identificateur de Module: | authn_file_module
Fichier Source: | mod_authn_file.c
Compatibilité: | Disponible depuis les versions 2.1 et supérieures d'Apache

Sommaire

Ce module permet aux frontaux d'authentification comme mod_auth_digest et mod_auth_basic d'authentifier les utilisateurs en les recherchant dans des fichiers de mots de passe au format texte. mod_authn_dbm fournit une fonctionnalité similaire.

Lorsqu'on utilise mod_auth_basic ou mod_auth_digest, ce module peut être invoqué en affectant la valeur file à la directive AuthBasicProvider ou AuthDigestProvider.

Traitement des bugs

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

Voir aussi

  • AuthBasicProvider
  • AuthDigestProvider
  • htpasswd
  • htdigest
  • Formats de mots de passe

Directive AuthUserFile

Description: | Définit le nom d'un fichier texte pour l'authentification contenant la liste des utilisateurs et de leurs mots de passe
Syntaxe: | AuthUserFile chemin-fichier
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authn_file

La directive AuthUserFile permet de définir le nom d'un fichier texte pour l'authentification contenant la liste des utilisateurs et de leurs mots de passe. chemin-fichier est le chemin vers le fichier des utilisateurs. S'il n'est pas absolu, il est considéré comme relatif au répertoire défini par la directive ServerRoot.

Chaque ligne du fichier des utilisateurs se compose du nom de l'utilisateur, du caractère ':' et du mot de passe chiffré. Si le même identifiant utilisateur est référencé plusieurs fois, mod_authn_file utilisera la première occurrence pour vérifier le mot de passe.

Le format du mot de passe chiffré dépend du frontal d'authentification utilisé (par exemple mod_auth_basic ou mod_auth_digest). Voir la documentation sur les Formats de mots de passe pour plus de détails.

Pour mod_auth_basic, utilisez le programme htpasswd fourni avec la distribution binaire, mais que vous trouverez aussi dans le répertoire src/support de l'arborescence des sources. Voir sa page de manuel pour plus de détails. En bref :

On crée un fichier de mots de passe nom-fichier avec nom-utilisateur comme identifiant initial. Le mot de passe correspondant sera alors demandé :

htpasswd -c nom-fichier nom-utilisateur

Pour ajouter ou modifier nom-utilisateur2 dans le fichier de mots de passe nom-fichier :

htpasswd nom-fichier nom-utilisateur2

Noter qu'une recherche dans de grands fichiers texte peut être très longue ; dans ce cas, il vaut mieux utiliser les fichiers DBM avec la directive AuthDBMUserFile.

Pour mod_auth_digest, vous devez utiliser le programme htdigest. Notez que vous ne pouvez pas mélanger des données utilisateur pour l'Authentification HTTP à base de condensé et des données pour l'Authentification de Base dans le même fichier.

Sécurité

Assurez-vous que le fichier AuthUserFile soit bien stocké en dehors de l'arborescence des documents du serveur web. Ne placez pas ce fichier dans le répertoire qu'il protège. Dans le cas contraire, les clients seraient en mesure de télécharger le fichier des mots de passe.


mod_authn_socache - Serveur Apache HTTP Version 2.4

Module Apache mod_authn_socache

Description: | Gère un cache des données d'authentification pour diminuer la charge des serveurs d'arrière-plan
Statut: | Base
Identificateur de Module: | authn_socache_module
Fichier Source: | mod_authn_socache.c
Compatibilité: | Versions 2.3 et ultérieures

Sommaire

Maintient un cache des données d'authentification pour limiter les sollicitations du serveur d'arrière-plan.

Mise en cache des données d'authentification

Certains utilisateurs qui mettent en oeuvre une authentification lourde s'appuyant par exemple sur des requêtes SQL (mod_authn_dbd) ont signalé une charge induite inacceptable sur leur fournisseur d'authentification. Cela se produit typiquement dans le cas où une page HTML contient des centaines d'objets (images, scripts, pages de styles, media, etc...), et où une requête pour cette page génère des centaines de sous-requêtes à effet immédiat pour des contenus supplémentaires authentifiés.

Pour résoudre ce problème, mod_authn_socache fournit une solution qui permet de maintenir un cache des données d'authentification.

Utilisation

Le cache d'authentification doit être utilisé lorsque les requêtes d'authentification induisent une charge significative sur le serveur, le serveur d'arrière-plan ou le réseau. Cette mise en cache n'apportera probablement aucune amélioration dans le cas d'une authentification à base de fichier (mod_authn_file) ou de base de données dbm (mod_authn_dbm) car ces méthodes sont de par leur conception rapides et légères (la mise en cache peut cependant s'avérer utile dans le cas où le fichier est situé sur un montage réseau). Les fournisseurs d'authentification basés sur SQL ou LDAP ont plus de chances de tirer parti de cette mise en cache, en particulier lorsqu'un problème de performances est détecté. mod_authnz_ldap gérant son propre cache, seul mod_authn_dbd est concerné par notre sujet.

Les principales règles à appliquer pour la mise en cache sont :

  1. Inclure le fournisseur pour lequel vous voulez effectuer une mise en cache dans une directive AuthnCacheProvideFor.
  2. Mettre socache avant le fournisseur pour lequel vous voulez effectuer une mise en cache dans votre directive AuthBasicProvider ou AuthDigestProvider.

Voici un exemple simple permettant d'accélérer mod_authn_dbd et utilisant dbm comme moteur de la mise en cache :

    #AuthnCacheSOCache est optionnel. S'il est défini, il l'est pour
    #l'ensemble du serveur
AuthnCacheSOCache dbm
<Directory "/usr/www/myhost/private">
    AuthType Basic
    AuthName "Cached Authentication Example"
    AuthBasicProvider socache dbd
    AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
    AuthnCacheProvideFor dbd
    Require valid-user
    #Optionnel
    AuthnCacheContext dbd-authn-example
</Directory>

La mise en cache avec les modules tiers

Les développeurs de modules doivent savoir que la mise en cache avec mod_authn_socache doit être activée dans leurs modules. La fonction de l'API ap_authn_cache_store permet de mettre en cache les données d'authentification qu'un fournisseur vient de rechercher ou de générer. Vous trouverez des exemples d'utilisation à r957072, où trois fournisseurs authn sont activés pour la mise en cache.

Directive AuthnCacheContext

Description: | Spécifie une chaîne de contexte à utiliser dans la clé du cache
Syntaxe: | AuthnCacheContext directory|server|chaîne-personnalisée
Défaut: | directory
Contexte: | répertoire
Statut: | Base
Module: | mod_authn_socache

Cette directive permet de spécifier une chaîne à utiliser avec le nom d'utilisateur fourni (et le domaine d'authentification - realm - dans le cas d'une authentification à base de condensés) lors de la construction d'une clé de cache. Ceci permet de lever l'ambiguïté entre plusieurs noms d'utilisateurs identiques servant différentes zones d'authentification sur le serveur.

Il y a deux valeurs spéciales pour le paramètre : directory, qui utilise le contexte de répertoire de la requête comme chaîne, et server, qui utilise le nom du serveur virtuel.

La valeur par défaut est directory, qui est aussi la définition la plus courante. Ceci est cependant loin d'être optimal, car par exemple, $app-base, $app-base/images, $app-base/scripts et $app-base/media possèderont chacun leur propre clé de cache. Il est préférable d'utiliser le fournisseur de mot de passe : par exemple un fichier htpasswd ou une table de base de données.

Les contextes peuvent être partagés entre différentes zones du serveur, où les données d'authentification sont partagées. Ceci est cependant susceptible de créer des trous de sécurité de type cross-site ou cross-application, et cette directive n'est donc pas disponible dans les contextes .htaccess.

Directive AuthnCacheEnable

Description: | Active la mise en cache de l'authentification en tout endroit
Syntaxe: | AuthnCacheEnable
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_authn_socache

Normalement, cette directive n'est pas nécessaire : l'activation est implicite si la mise en cache de l'authentification a été activée en tout autre endroit du fichier httpd.conf. Par contre, si cette mise en cache n'a pas été activée, par défaut, elle ne sera pas initialisée, et ne sera donc pas disponible dans un contexte de fichier .htaccess. Cette directive permet d'être sûr que la mise en cache a bien été activée et pourra donc être utilisée dans les fichiers .htaccess.

Directive AuthnCacheProvideFor

Description: | Spécifie le fournisseur pour lequel on veut effectuer une mise en cache
Syntaxe: | AuthnCacheProvideFor fournisseur-authn [...]
Défaut: | None
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authn_socache

Cette directive permet de spécifier un ou plusieurs fournisseurs pour le(s)quel(s) on veut effectuer une mise en cache. Les données d'authentification trouvées par un fournisseur non spécifié dans une directive AuthnCacheProvideFor ne seront pas mises en cache.

Par exemple, pour mettre en cache les données d'authentification trouvées par mod_authn_dbd ou par un fournisseur personnalisé mon-fournisseur, et ne pas mettre en cache celles trouvées par les fournisseurs légers comme file ou dbm :

AuthnCacheProvideFor dbd mon-fournisseur

Directive AuthnCacheSOCache

Description: | Sélectionne le fournisseur socache d'arrière-plan à utiliser
Syntaxe: | AuthnCacheSOCache nom-fournisseur[:arguments-fournisseur]
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_authn_socache
Compatibilité: | Les arguments optionnels du fournisseur sont disponibles à partir de la version 2.4.7 du serveur HTTP Apache

Cette définition s'applique à l'ensemble du serveur et permet de sélectionner un fournisseur pour le cache d'objets partagés, ainsi que des arguments éventuels pour ce fournisseur. Les fournisseurs disponibles sont, entre autres, "dbm", "dc", "memcache", ou "shmcb", chacun d'entre eux nécessitant le chargement du module approprié. Si elle est absente, c'est la valeur par défaut pour votre plate-forme qui sera utilisée.

Directive AuthnCacheTimeout

Description: | Définit une durée de vie pour les entrées du cache
Syntaxe: | AuthnCacheTimeout durée-de-vie (secondes)
Défaut: | 300 (5 minutes)
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authn_socache

La mise en cache des données d'authentification peut constituer un trou de sécurité, bien qu'un mise en cache de courte durée ne posera probablement pas de problème. En général, il est conseillé de conserver les entrées du cache de façon à ce que la charge du serveur d'arrière-plan reste normale, mais pas plus longtemps ; une durée de vie plus longue peut être paramétrée si les changements d'utilisateurs et de mots de passe sont peu fréquents. La durée de vie par défaut de 300 secondes (5 minutes) est à la fois raisonnable et suffisamment importante pour réduire la charge d'un serveur d'arrière-plan comme dbd (requêtes SQL).

Cette durée de vie ne doit pas être confondue avec la durée de vie de session qui est un tout autre sujet. Cependant, vous devez utiliser votre logiciel de gestion de session pour vérifier si les données d'authentification mises en cache peuvent allonger accidentellement une session, et en tenir compte lorsque vous définissez la durée de vie.


mod_authnz_fcgi - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_authnz_fcgi

Description: | Allows a FastCGI authorizer application to handle Apache httpd authentication and authorization
Status: | Extension
Module Identifier: | authnz_fcgi_module
Source File: | mod_authnz_fcgi.c
Compatibility: | Available in version 2.4.10 and later

Summary

This module allows FastCGI authorizer applications to authenticate users and authorize access to resources. It supports generic FastCGI authorizers which participate in a single phase for authentication and authorization as well as Apache httpd-specific authenticators and authorizors which participate in one or both phases.

FastCGI authorizers can authenticate using user id and password, such as for Basic authentication, or can authenticate using arbitrary mechanisms.

Bugfix checklist

  • httpd changelog
  • Known issues
  • Report a bug

See also

  • Authentication, Authorization, and Access Control
  • mod_auth_basic
  • fcgistarter
  • mod_proxy_fcgi

Invocation modes

The invocation modes for FastCGI authorizers supported by this module are distinguished by two characteristics, type and auth mechanism.

Type is simply authn for authentication, authz for authorization, or authnz for combined authentication and authorization.

Auth mechanism refers to the Apache httpd configuration mechanisms and processing phases, and can be AuthBasicProvider, Require, or check_user_id. The first two of these correspond to the directives used to enable participation in the appropriate processing phase.

Descriptions of each mode:

Type authn, mechanism AuthBasicProvider
In this mode, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is set to AUTHENTICATOR. The application must be defined as provider type authn using AuthnzFcgiDefineProvider and enabled with AuthBasicProvider. When invoked, the application is expected to authenticate the client using the provided user id and password. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
    die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
    die if !$ENV{'REMOTE_PASSWD'};
    die if !$ENV{'REMOTE_USER'};

    print STDERR "This text is written to the web server error log.\n";

    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
        $ENV{'REMOTE_PASSWD'} eq "bar" ) {
        print "Status: 200\n";
        print "Variable-AUTHN_1: authn_01\n";
        print "Variable-AUTHN_2: authn_02\n";
        print "\n";
    }
    else {
        print "Status: 401\n\n";
    }
}
Example configuration:
AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10102/
<Location "/protected/">
  AuthType Basic
  AuthName "Restricted"
  AuthBasicProvider FooAuthn
  Require ...
</Location>
Type authz, mechanism Require
In this mode, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is set to AUTHORIZER. The application must be defined as provider type authz using AuthnzFcgiDefineProvider. When invoked, the application is expected to authorize the client using the provided user id and other request data. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHORIZER";
    die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
    die if $ENV{'REMOTE_PASSWD'};

    print STDERR "This text is written to the web server error log.\n";

    if ($ENV{'REMOTE_USER'} eq "foo1") {
        print "Status: 200\n";
        print "Variable-AUTHZ_1: authz_01\n";
        print "Variable-AUTHZ_2: authz_02\n";
        print "\n";
    }
    else {
        print "Status: 403\n\n";
    }
}
Example configuration:
AuthnzFcgiDefineProvider authz FooAuthz fcgi://localhost:10103/
<Location "/protected/">
  AuthType ...
  AuthName ...
  AuthBasicProvider ...
  Require FooAuthz
</Location>
Type authnz, mechanism AuthBasicProvider + Require
In this mode, which supports the web server-agnostic FastCGI AUTHORIZER protocol, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is not set. The application must be defined as provider type authnz using AuthnzFcgiDefineProvider. The application is expected to handle both authentication and authorization in the same invocation using the user id, password, and other request data. The invocation occurs during the Apache httpd API authentication phase. If the application returns 200 and the same provider is invoked during the authorization phase (via Require), mod_authnz_fcgi will return success for the authorization phase without invoking the application. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'};
    die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";
    die if !$ENV{'REMOTE_PASSWD'};
    die if !$ENV{'REMOTE_USER'};

    print STDERR "This text is written to the web server error log.\n";

    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
        $ENV{'REMOTE_PASSWD'} eq "bar" &&
        $ENV{'REQUEST_URI'} =~ m%/bar/.*%) {
        print "Status: 200\n";
        print "Variable-AUTHNZ_1: authnz_01\n";
        print "Variable-AUTHNZ_2: authnz_02\n";
        print "\n";
    }
    else {
        print "Status: 401\n\n";
    }
}
Example configuration:
AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
<Location "/protected/">
  AuthType Basic
  AuthName "Restricted"
  AuthBasicProvider FooAuthnz
  Require FooAuthnz
</Location>
Type authn, mechanism check_user_id
In this mode, FCGI_ROLE is set to AUTHORIZER and FCGI_APACHE_ROLE is set to AUTHENTICATOR. The application must be defined as provider type authn using AuthnzFcgiDefineProvider. AuthnzFcgiCheckAuthnProvider specifies when it is called. Example application:
#!/usr/bin/perl
use FCGI;
my $request = FCGI::Request();
while ($request->Accept() >= 0) {
    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
    die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";

    # This authorizer assumes that the RequireBasicAuth option of
    # AuthnzFcgiCheckAuthnProvider is On:
    die if !$ENV{'REMOTE_PASSWD'};
    die if !$ENV{'REMOTE_USER'};

    print STDERR "This text is written to the web server error log.\n";

    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
        $ENV{'REMOTE_PASSWD'} eq "bar" ) {
        print "Status: 200\n";
        print "Variable-AUTHNZ_1: authnz_01\n";
        print "Variable-AUTHNZ_2: authnz_02\n";
        print "\n";
    }
    else {
        print "Status: 401\n\n";
        # If a response body is written here, it will be returned to
        # the client.
    }
}
Example configuration:
AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10103/
<Location "/protected/">
  AuthType ...
  AuthName ...
  AuthnzFcgiCheckAuthnProvider FooAuthn \
                               Authoritative On \
                               RequireBasicAuth Off \
                               UserExpr "%{reqenv:REMOTE_USER}"
  Require ...
</Location>

Additional examples

  1. If your application supports the separate authentication and authorization roles (AUTHENTICATOR and AUTHORIZER), define separate providers as follows, even if they map to the same application:
    AuthnzFcgiDefineProvider authn  FooAuthn  fcgi://localhost:10102/
AuthnzFcgiDefineProvider authz  FooAuthz  fcgi://localhost:10102/
    Specify the authn provider on AuthBasicProvider and the authz provider on Require:
    AuthType Basic
AuthName "Restricted"
AuthBasicProvider FooAuthn
Require FooAuthz
  2. If your application supports the generic AUTHORIZER role (authentication and authorizer in one invocation), define a single provider as follows:
    AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
    Specify the authnz provider on both AuthBasicProvider and Require:
    AuthType Basic
AuthName "Restricted"
AuthBasicProvider FooAuthnz
Require FooAuthnz

Limitations

The following are potential features which are not currently implemented:

Apache httpd access checker
The Apache httpd API access check phase is a separate phase from authentication and authorization. Some other FastCGI implementations implement this phase, which is denoted by the setting of FCGI_APACHE_ROLE to ACCESS_CHECKER.
Local (Unix) sockets or pipes
Only TCP sockets are currently supported.
Support for mod_authn_socache
mod_authn_socache interaction should be implemented for applications which participate in Apache httpd-style authentication.
Support for digest authentication using AuthDigestProvider
This is expected to be a permanent limitation as there is no authorizer flow for retrieving a hash.
Application process management
This is expected to be permanently out of scope for this module. Application processes must be controlled by other means. For example, fcgistarter can be used to start them.
AP_AUTH_INTERNAL_PER_URI
All providers are currently registered as AP_AUTH_INTERNAL_PER_CONF, which means that checks are not performed again for internal subrequests with the same access control configuration as the initial request.
Protocol data charset conversion
If mod_authnz_fcgi runs in an EBCDIC compilation environment, all FastCGI protocol data is written in EBCDIC and expected to be received in EBCDIC.
Multiple requests per connection
Currently the connection to the FastCGI authorizer is closed after every phase of processing. For example, if the authorizer handles separate authn and authz phases then two connections will be used.
URI Mapping
URIs from clients can't be mapped, such as with the ProxyPass used with FastCGI responders.

Logging

  1. Processing errors are logged at log level error and higher.
  2. Messages written by the application are logged at log level warn.
  3. General messages for debugging are logged at log level debug.
  4. Environment variables passed to the application are logged at log level trace2. The value of the REMOTE_PASSWD variable will be obscured, but any other sensitive data will be visible in the log.
  5. All I/O between the module and the FastCGI application, including all environment variables, will be logged in printable and hex format at log level trace5. All sensitive data will be visible in the log.

LogLevel can be used to configure a log level specific to mod_authnz_fcgi. For example:

LogLevel info authnz_fcgi:trace8

AuthnzFcgiCheckAuthnProvider Directive

Description: | Enables a FastCGI application to handle the check_authn authentication hook.
Syntax: | AuthnzFcgiCheckAuthnProvider provider-name|None option ...
Default: | none
Context: | directory
Status: | Extension
Module: | mod_authnz_fcgi

This directive is used to enable a FastCGI authorizer to handle a specific processing phase of authentication or authorization.

Some capabilities of FastCGI authorizers require enablement using this directive instead of AuthBasicProvider:

  • Non-Basic authentication; generally, determining the user id of the client and returning it from the authorizer; see the UserExpr option below
  • Selecting a custom response code; for a non-200 response from the authorizer, the code from the authorizer will be the status of the response
  • Setting the body of a non-200 response; if the authorizer provides a response body with a non-200 response, that body will be returned to the client; up to 8192 bytes of text are supported
provider-name
This is the name of a provider defined with AuthnzFcgiDefineProvider.
None
Specify None to disable a provider enabled with this directive in an outer scope, such as in a parent directory.
option
The following options are supported:
Authoritative On|Off (default On)
This controls whether or not other modules are allowed to run when this module has a FastCGI authorizer configured and it fails the request.
DefaultUser userid
When the authorizer returns success and UserExpr is configured and evaluates to an empty string (e.g., authorizer didn't return a variable), this value will be used as the user id. This is typically used when the authorizer has a concept of guest, or unauthenticated, users and guest users are mapped to some specific user id for logging and other purposes.
RequireBasicAuth On|Off (default Off)
This controls whether or not Basic auth is required before passing the request to the authorizer. If required, the authorizer won't be invoked without a user id and password; 401 will be returned for a request without that.
UserExpr expr (no default)
When Basic authentication isn't provided by the client and the authorizer determines the user, this expression, evaluated after calling the authorizer, determines the user. The expression follows ap_expr syntax and must resolve to a string. A typical use is to reference a Variable-XXX setting returned by the authorizer using an option like UserExpr "%{reqenv:XXX}". If this option is specified and the user id can't be retrieved using the expression after a successful authentication, the request will be rejected with a 500 error.

AuthnzFcgiDefineProvider Directive

Description: | Defines a FastCGI application as a provider for authentication and/or authorization
Syntax: | AuthnzFcgiDefineProvider type provider-name backend-address
Default: | none
Context: | server config
Status: | Extension
Module: | mod_authnz_fcgi

This directive is used to define a FastCGI application as a provider for a particular phase of authentication or authorization.

type
This must be set to authn for authentication, authz for authorization, or authnz for a generic FastCGI authorizer which performs both checks.
provider-name
This is used to assign a name to the provider which is used in other directives such as AuthBasicProvider and Require.
backend-address
This specifies the address of the application, in the form fcgi://hostname:port/. The application process(es) must be managed independently, such as with fcgistarter.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_authnz_ldap - Serveur Apache HTTP Version 2.4

Module Apache mod_authnz_ldap

Description: | Permet d'utiliser un annuaire LDAP pour l'authentification HTTP de base.
Statut: | Extension
Identificateur de Module: | authnz_ldap_module
Fichier Source: | mod_authnz_ldap.c
Compatibilité: | Dosponible depuis les versions 2.1 et supérieures d'Apache

Sommaire

Ce module permet aux frontaux d'authentification comme mod_auth_basic d'authentifier les utilisateurs via un annuaire ldap.

mod_authnz_ldap supporte les fonctionnalités suivantes :

  • Support vérifié du OpenLDAP SDK (versions 1.x et 2.x), du Novell LDAP SDK et du SDK iPlanet (Netscape).
  • Implémentation de politiques d'autorisation complexes en les définissant via des filtres LDAP.
  • Mise en oeuvre d'une mise en cache des opérations LDAP élaborée via mod_ldap.
  • Support de LDAP via SSL (nécessite le SDK Netscape) ou TLS (nécessite le SDK OpenLDAP 2.x ou le SDK LDAP Novell).

Lorsqu'on utilise mod_auth_basic, ce module est invoqué en affectant la valeur ldap à la directive AuthBasicProvider.

Traitement des bugs

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

Voir aussi

  • mod_ldap
  • mod_auth_basic
  • mod_authz_user
  • mod_authz_groupfile

Sommaire

  • Mises en garde à caractère général
  • Mode opératoire
    • La phase d'authentification
    • La phase d'autorisation
  • Les directives requises
    • Require ldap-user
    • Require ldap-group
    • Require ldap-dn
    • Require ldap-attribute
    • Require ldap-filter
  • Exemples
  • Utilisation de TLS
  • Utilisation de SSL
  • Mise à disposition des informations de connexion
  • Utilisation d'Active Directory
  • Utilisation de Microsoft FrontPage avec mod_authnz_ldap
    • Comment ça marche
    • Mises en garde

Mises en garde à caractère général

Ce module effectue une mise en cache des résultats du processus d'authentification et d'autorisation en fonction de la configuration du module mod_ldap. Les modifications effectuées au niveau du serveur LDAP d'arrière-plan comme les verrouillages ou révocations d'utilisateurs, les changements de mot de passe, ou les changements d'appartenance à un groupe (et cette liste n'est pas exhaustive), ne seront pas immédiatement propagées jusqu'au serveur HTTP. Consultez les directives du module mod_ldap pour plus de détails à propos de la configuration de la mise en cache.

Mode opératoire

L'utilisateur se voit accorder l'accès selon un processus en deux phases. La première phase est l'authentification, au cours de laquelle le fournisseur d'authentification mod_authnz_ldap vérifie que les informations de connexion de l'utilisateur sont valides. Elle est aussi connue sous le nom de phase de recherche/connexion (NdT : en anglais ou dans le code source : search/bind). La deuxième phase est l'autorisation, au cours de laquelle mod_authnz_ldap détermine si l'utilisateur authentifié a la permission d'accéder à la ressource considérée. Elle est aussi connue sous le nom de phase de comparaison (compare).

mod_authnz_ldap comporte un fournisseur d'authentification authn_ldap et un gestionnaire d'autorisation authz_ldap. Le fournisseur d'authentification authn_ldap peut être invoqué en affectant la valeur ldap à la directive AuthBasicProvider. Le gestionnaire d'autorisation authz_ldap enrichit la liste des types d'autorisations de la directive Require en y ajoutant les valeurs ldap-user, ldap-dn et ldap-group.

La phase d'authentification

Au cours de la phase d'authentification, mod_authnz_ldap recherche une entrée de l'annuaire LDAP qui correspond au nom d'utilisateur fourni par le client HTTP. Si une correspondance unique est trouvée, mod_authnz_ldap tente de se connecter au serveur hébergeant l'annuaire LDAP en utilisant le DN de l'entrée et le mot de passe fourni par le client HTTP. Comme ce processus effectue tout d'abord une recherche, puis une connexion, il est aussi connu sous le nom de phase de recherche/connexion. Voici le détail des étapes constituant la phase de recherche/connexion :

  1. Confection d'un filtre de recherche en combinant les attribut et filtre définis par la directive AuthLDAPURL avec le nom d'utilisateur et le mot de passe fournis par le client HTTP.
  2. Recherche dans l'annuaire LDAP en utilisant le filtre confectionné précédemment. Si le résultat de la recherche est négatif ou comporte plusieurs entrées, refus ou restriction de l'accès.
  3. Extraction du DN (distinguished name) de l'entrée issue du résultat de la recherche, et tentative de connexion au serveur LDAP en utilisant ce DN et le mot de passe fournis par le client HTTP. Si la connexion échoue, refus ou restriction de l'accès.

Les directives utilisées durant la phase de recherche/connexion sont les suivantes :

AuthLDAPURL | Spécifie le serveur LDAP, le DN de base, l'attribut à utiliser pour la recherche, ainsi que les filtres de recherche supplémentaires.
AuthLDAPBindDN | Un DN optionnel pour se connecter durant la phase de recherche.
AuthLDAPBindPassword | Un mot de passe optionnel pour se connecter durant la phase de recherche.

La phase d'autorisation

Au cours de la phase d'autorisation, mod_authnz_ldap tente de déterminer si l'utilisateur est autorisé à accéder à la ressource considérée. Une grande partie de cette vérification consiste pour mod_authnz_ldap en des opérations de comparaison au niveau du serveur LDAP. C'est pourquoi cette phase est aussi connue sous le nom de phase de comparaison. mod_authnz_ldap accepte les directives Require suivantes pour déterminer si les informations de connexion permettent d'accorder l'accès à l'utilisateur :

  • Avec la directive Require ldap-user, l'autorisation d'accès est accordée si le nom d'utilisateur spécifié par la directive correspond au nom d'utilisateur fourni par le client.
  • Avec la directive Require ldap-dn, l'autorisation d'accès est accordée si le DN spécifié par la directive correspond au DN extrait du résultat de la recherche dans l'annuaire LDAP.
  • Avec la directive Require ldap-group, l'autorisation d'accès est accordée si le DN extrait du résultat de la recherche dans l'annuaire LDAP (ou le nom d'utilisateur fourni par le client) appartient au groupe LDAP spécifié par la directive, ou éventuellement à un de ses sous-groupes.
  • Avec la directive Require ldap-attribute, l'autorisation d'accès est accordée si la valeur de l'attribut extraite de la recherche dans l'annuaire LDAP correspond à la valeur spécifiée par la directive.
  • Avec la directive Require ldap-filter, l'autorisation d'accès est accordée si le filtre de recherche renvoie un objet utilisateur unique qui corresponde au DN de l'utilisateur authentifié.
  • dans tous les autres cas, refus ou restriction de l'accès.

Sous réserve du chargement de modules d'autorisation supplémentaires, d'autres valeurs de la directive Require peuvent être spécifiées.

  • L'accès est accordé à tous les utilisateurs authentifiés si une directive Require valid-user est présente (nécessite le module mod_authz_user).
  • Avec la directive Require group, l'autorisation d'accès est accordée si le module mod_authz_groupfile a été chargé et si la directive AuthGroupFile a été définie.
  • etc...

Durant la phase de comparaison, mod_authnz_ldap utilise les directives suivantes :

AuthLDAPURL | On utilise l'attribut spécifié dans l'URL pour les opérations de comparaison initiées par la directive Require ldap-user.
AuthLDAPCompareDNOnServer | Détermine le comportement de la directive Require ldap-dn.
AuthLDAPGroupAttribute | Détermine l'attribut utilisé pour les opérations de comparaison initiées par la directive Require ldap-group.
AuthLDAPGroupAttributeIsDN | Spécifie si l'on doit utiliser le DN ou le nom de l'utilisateur lors des opérations de comparaison initiées par la directive Require ldap-group.
AuthLDAPMaxSubGroupDepth | Détermine la profondeur maximale de l'arborescence des sous-groupes qui seront évalués au cours des opérations de comparaisons initiées par la directive Require ldap-group.
AuthLDAPSubGroupAttribute | Détermine l'attribut à utiliser lors de l'extraction de membres de sous-groupes du groupe courant au cours des opérations de comparaison initiées par la directive Require ldap-group.
AuthLDAPSubGroupClass | Spécifie les valeurs de classe d'objet LDAP à utiliser pour déterminer si les objets extraits de l'annuaire sont bien des objets de type groupe (et non des objets de type utilisateur), au cours du traitement des sous-groupes initié par la directive Require ldap-group.

Les directives requises

Les directives Require d'Apache sont utilisées au cours de la phase d'autorisation afin de s'assurer que l'utilisateur est autorisé à accéder à une ressource. mod_authnz_ldap enrichit la liste des types d'autorisations avec les valeurs ldap-user, ldap-dn, ldap-group, ldap-attribute et ldap-filter. D'autres types d'autorisations sont disponibles, sous réserve du chargement de modules d'autorisation supplémentaires.

Depuis la version 2.4.8, les directives require LDAP supportent les expressions.

Require ldap-user

La directive Require ldap-user permet de spécifier les noms des utilisateurs autorisés à accéder à la ressource. Lorsque mod_authnz_ldap a extrait un DN unique de l'annuaire LDAP, il effectue une opération de comparaison LDAP en utilisant le nom d'utilisateur spécifié par la directive Require ldap-user, pour vérifier si ce nom d'utilisateur correspond à l'entrée LDAP extraite. On peut accorder l'accès à plusieurs utilisateurs en plaçant plusieurs nom d'utilisateurs sur la même ligne séparés par des espaces. Si un nom d'utilisateur contient des espaces, il doit être entouré de guillemets. On peut aussi accorder l'accès à plusieurs utilisateurs en utilisant une directive Require ldap-user par utilisateur. Par exemple, avec la directive AuthLDAPURL définie à ldap://ldap/o=Example?cn (spécifiant donc que l'attribut cn sera utilisé pour les recherches), on pourra utiliser les directives Require suivantes pour restreindre l'accès :

Require ldap-user "Barbara Jenson"
Require ldap-user "Fred User"
Require ldap-user "Joe Manager"

De par la manière dont mod_authnz_ldap traite cette directive, Barbara Jenson peut s'authentifier comme Barbara Jenson, Babs Jenson ou tout autre cn sous lequel elle est enregistrée dans l'annuaire LDAP. Une seule ligne Require ldap-user suffit pour toutes les valeurs de l'attribut dans l'entrée LDAP de l'utilisateur.

Si l'attribut uid avait été spécifié à la place de l'attribut cn dans l'URL précédente, les trois lignes ci-dessus auraient pû être condensées en une seule ligne :

Require ldap-user bjenson fuser jmanager

Require ldap-group

Cette directive permet de spécifier un groupe LDAP dont les membres auront l'autorisation d'accès. Elle prend comme argument le DN du groupe LDAP. Note : n'entourez pas le nom du groupe avec des guillemets. Par exemple, supposons que l'entrée suivante existe dans l'annuaire LDAP :

dn: cn=Administrators, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Barbara Jenson, o=Example
uniqueMember: cn=Fred User, o=Example

La directive suivante autoriserait alors l'accès à Fred et Barbara :

Require ldap-group cn=Administrators, o=Example

Les membres peuvent aussi se trouver dans les sous-groupes du groupe LDAP spécifié si la directive AuthLDAPMaxSubGroupDepth a été définie à une valeur supérieure à 0. Par exemple, supposons que les entrées suivantes existent dans l'annuaire LDAP :

dn: cn=Employees, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Managers, o=Example
uniqueMember: cn=Administrators, o=Example
uniqueMember: cn=Users, o=Example

dn: cn=Managers, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Bob Ellis, o=Example
uniqueMember: cn=Tom Jackson, o=Example

dn: cn=Administrators, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Barbara Jenson, o=Example
uniqueMember: cn=Fred User, o=Example

dn: cn=Users, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Allan Jefferson, o=Example
uniqueMember: cn=Paul Tilley, o=Example
uniqueMember: cn=Temporary Employees, o=Example

dn: cn=Temporary Employees, o=Example
objectClass: groupOfUniqueNames
uniqueMember: cn=Jim Swenson, o=Example
uniqueMember: cn=Elliot Rhodes, o=Example

Les directives suivantes autoriseraient alors l'accès à Bob Ellis, Tom Jackson, Barbara Jenson, Fred User, Allan Jefferson, et Paul Tilley, mais l'interdiraient à Jim Swenson, ou Elliot Rhodes (car ils sont situés dans un sous-groupe de niveau de profondeur 2) :

Require ldap-group cn=Employees, o=Example
AuthLDAPMaxSubGroupDepth 1

Le comportement de cette directive est modifié par les directives AuthLDAPGroupAttribute, AuthLDAPGroupAttributeIsDN, AuthLDAPMaxSubGroupDepth, AuthLDAPSubGroupAttribute, et AuthLDAPSubGroupClass.

Require ldap-dn

La directive Require ldap-dn permet à l'administrateur d'accorder l'utorisation d'accès en fonction du DN. Elle permet de spécifier un DN pour lequel l'accès est autorisé. Si le DN extrait de l'annuaire correspond au DN spécifié par la directive Require ldap-dn, l'autorisation d'accès est accordée. Note : n'entourez pas Le DN de guillemets.

La directive suivante accorderait l'accès à un DN spécifique :

Require ldap-dn cn=Barbara Jenson, o=Example

Le comportement ce cette directive est modifié par la directive AuthLDAPCompareDNOnServer.

Require ldap-attribute

La directive Require ldap-attribute permet à l'administrateur d'accorder l'autorisation d'accès en fonction des attributs de l'utilisateur authentifié dans l'annuaire LDAP. Si la valeur de l'attribut dans l'annuaire correspond à la valeur spécifiée par la directive, l'autorisation d'accès est accordée.

La directive suivante accorderait l'autorisation d'accès à tout utilisateur dont l'attribut employeeType a pour valeur "actif" :

Require ldap-attribute employeeType="active"

Plusieurs paires attribut/valeur peuvent être spécifiées par une même directive en les séparant par des espaces, ou en définissant plusieurs directives Require ldap-attribute. La logique sous-jacente à une liste de paires attribut/valeur est une opération OU. L'autorisation d'accès sera accordée si au moins une paire attribut/valeur de la liste spécifiée correspond à la paire attribut/valeur de l'utilisateur authentifié. Si elle contient des espaces, la valeur, et seulement la valeur, doit être entourée de guillemets.

La directive suivante accorderait l'autorisation d'accès à tout utilisateur dont l'attribut city aurait pour valeur "San Jose", ou donc l'attribut status aurait pour valeur "actif" :

Require ldap-attribute city="San Jose" status="active"

Require ldap-filter

La directive Require ldap-filter permet à l'administrateur d'accorder l'autorisation d'accès en fonction d'un filtre de recherche LDAP complexe. L'autorisation d'accès est accordée si le DN renvoyé par le filtre de recherche correspond au DN de l'utilisateur authentifié.

La directive suivante accorderait l'autorisation d'accès à tout utilisateur possédant un téléphone cellulaire et faisant partie du département "marketing" :

Require ldap-filter &(cell=*)(department=marketing)

Alors que la directive Require ldap-attribute se contente d'une simple comparaison d'attributs, la directive Require ldap-filter effectue une opération de recherche dans l'annuaire LDAP en utilisant le filtre de recherche spécifié. Si une simple comparaison d'attributs suffit, l'opération de comparaison effectuée par ldap-attribute sera plus rapide que l'opération de recherche effectuée par ldap-filter, en particulier dans le cas d'un annuaire LDAP de grande taille.

Exemples

  • Accorde l'autorisation d'accès à tout utilisateur présent dans l'annuaire LDAP, en utilisant son UID pour effectuer la recherche :
    AuthLDAPURL "ldap://ldap1.example.com:389/ou=People, o=Example?uid?sub?(objectClass=*)"
Require valid-user
  • L'exemple suivant est similaire au précédent, mais les champs dont les valeurs par défaut conviennent sont omis. Notez aussi la présence d'un annuaire LDAP redondant :
    AuthLDAPURL "ldap://ldap1.example.com ldap2.example.com/ou=People, o=Example"
Require valid-user
  • Encore un exemple similaire aux précédents, mais cette fois, c'est l'attribut cn qui est utilisé pour la recherche à la place de l'UID. Notez que ceci peut poser problème si plusieurs utilisateurs de l'annuaire partagent le même cn, car une recherche sur le cn doit retourner une entrée et une seule. C'est pourquoi cette approche n'est pas recommandée : il est préférable de choisir un attribut de votre annuaire dont l'unicité soit garantie, comme uid.
    AuthLDAPURL "ldap://ldap.example.com/ou=People, o=Example?cn"
Require valid-user
  • Accorde l'autorisation d'accès à tout utilisateur appartenant au groupe Administrateurs. Les utilisateurs doivent s'authentifier en utilisant leur UID :
    AuthLDAPURL ldap://ldap.example.com/o=Example?uid
Require ldap-group cn=Administrators, o=Example
  • Accorde l'accès à tout utilisateur appartenant au groupe dont le nom correspond au nom d'hôte du serveur virtuel. Dans cet exemple, on utilise une expression pour construire le filtre.
    AuthLDAPURL ldap://ldap.example.com/o=Example?uid
Require ldap-group cn=%{SERVER_NAME}, o=Example
  • Pour l'exemple suivant, on suppose que tout utilisateur de chez Example qui dispose d'un bippeur alphanumérique possèdera un attribut LDAP qpagePagerID. Seuls ces utilisateurs (authentifiés via leur UID) se verront accorder l'autorisation d'accès :
    AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(qpagePagerID=*)
Require valid-user

  • L'exemple suivant illustre la puissance des filtres pour effectuer des requêtes complexes. Sans les filtres, il aurait été nécessaire de créer un nouveau groupe LDAP et de s'assurer de la synchronisation des membres du groupe avec les utilisateurs possédant un bippeur. Tout devient limpide avec les filtres. Nous avons pour but d'accorder l'autorisation d'accès à tout utilisateur disposant d'un bippeur ainsi qu'à Joe Manager qui ne possède pas de bippeur, mais doit tout de même pouvoir accéder à la ressource :

    AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(|(qpagePagerID=*)(uid=jmanager))
Require valid-user

    Ce dernier exemple peut sembler confus au premier abord ; en fait, il permet de mieux comprendre à quoi doit ressembler le filtre en fonction de l'utilisateur qui se connecte. Si Fred User se connecte en tant que fuser, le filtre devra ressembler à :

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))

    Un recherche avec le filtre ci-dessus ne retournera un résultat positif que si fuser dispose d'un bippeur. Si Joe Manager se connecte en tant que jmanager, le filtre devra ressembler à :

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))

    Un recherche avec le filtre ci-dessus retournera un résultat positif que jmanager dispose d'un bippeur ou non

Utilisation de TLS

Pour l'utilisation de TLS, voir les directives du module mod_ldap LDAPTrustedClientCert, LDAPTrustedGlobalCert et LDAPTrustedMode.

Un second paramètre optionnel peut être ajouté à la directive AuthLDAPURL pour remplacer le type de connexion par défaut défini par la directive LDAPTrustedMode. Ceci permettra de promouvoir la connexion établie via une URL du type ldap:// au statut de connection sécurisée sur le même port.

Utilisation de SSL

Pour l'utilisation de SSL, voir les directives du module mod_ldap LDAPTrustedClientCert, LDAPTrustedGlobalCert et LDAPTrustedMode.

Pour spécifier un serveur LDAP sécurisé, utilisez ldaps:// au lieu de ldap:// dans la directive AuthLDAPURL.

Mise à disposition des informations de connexion

Au cours du processus d'authentification, les attributs LDAP spécifiés par la directive authldapurl sont enregistrés dans des variables d'environnement préfixées par la chaîne "AUTHENTICATE_".

Au cours du processus d'autorisation, les attributs LDAP spécifiés par la directive authldapurl sont enregistrés dans des variables d'environnement préfixées par la chaîne "AUTHORIZE_".

Si les champs attribut contiennent le nom, le CN et le numéro de téléphone d'un utilisateur, un programme CGI pourra accéder à ces informations sans devoir effectuer une autre requête LDAP pour les extraire de l'annuaire.

Ceci a pour effet de simplifier considérablement le code et la configuration nécessaire de certaines applications web.

Utilisation d'Active Directory

Active Directory peut supporter plusieurs domaines à la fois. Pour faire la distinction entre les utilisateurs de plusieurs domaines, on peut ajouter à l'entrée de l'utilisateur dans l'annuaire un identifiant appelé Nom Principal d'Utilisateur (User Principle Name ou UPN). Cet UPN se compose en général du nom de compte de l'utilisateur, suivi du nom du domaine considéré, par exemple untel@nz.example.com.

Vous voudrez probablement configurer le module mod_authnz_ldap afin de pouvoir authentifier les utilisateurs de n'importe quel domaine de la forêt Active Directory. Ainsi, untel@nz.example.com et untel@au.example.com pourront être authentifiés en une seule fois par la même requête.

Pour y parvenir, on utilise le concept de Catalogue Global d'Active Directory. Ce Catalogue Global est une copie en lecture seule des attributs sélectionnés de tous les serveurs de la forêt Active Directory. Une requête vers le Catalogue Global permet donc d'atteindre tous les domaines en une seule fois, sans avoir à se connecter aux différents serveurs, via des liaisons dont certaines peuvent être lentes.

Lorsqu'il est activé, la Catalogue Global est un serveur d'annuaire indépendant accessible sur le port 3268 (3269 pour SSL). Pour rechercher un utilisateur, effectuez une recherche sur l'attribut userPrincipalName, avec une base de recherche vide, comme suit :

AuthLDAPBindDN apache@example.com
AuthLDAPBindPassword password
AuthLDAPURL ldap://10.0.0.1:3268/?userPrincipalName?sub

Les utilisateurs devront s'authentifier en entrant leur UPN, de la formeuntel@nz.example.com.

Utilisation de Microsoft FrontPage avec mod_authnz_ldap

Normalement, FrontPage utilise des fichiers utilisateur/groupe spécifiques à FrontPage-web (c'est à dire les modules mod_authn_file et mod_authz_groupfile) pour effectuer toute l'authentification. Malheureusement, il ne suffit pas de modifier l'authentification LDAP en ajoutant les directives appropriées, car ceci corromprait les formulaires de Permissions dans le client FrontPage, qui sont censés modifier les fichiers d'autorisation standards au format texte.

Lorsqu'un site web FrontPage a été créé, lui adjoindre l'authentification LDAP consiste à ajouter les directives suivantes à chaque fichier .htaccess qui sera créé dans le site web :

AuthLDAPURL       "the url"
AuthGroupFile     "mygroupfile"
Require group     "mygroupfile"

Comment ça marche

FrontPage restreint l'accès à un site web en ajoutant la directive Require valid-user aux fichiers .htaccess. La directive Require valid-user permettra l'accès à tout utilisateur valide du point de vue LDAP. Cela signifie que tout utilisateur possédant une entrée dans l'annuaire LDAP sera considéré comme valide, alors que FrontPage ne considère comme valides que les utilisateurs enregistrés dans le fichier des utilisateurs local. En remplaçant l'autorisation par groupe LDAP par une autorisation par fichier de groupe, Apache sera en mesure de consulter le fichier des utilisateurs local (géré par FrontPage) - au lieu de l'annuaire LDAP - lors du processus d'autorisation des utilisateurs.

Une fois les directives ajoutées selon ce qui précède, les utilisateurs FrontPage pourront effectuer toutes les opérations de gestion à partir du client FrontPage.

Avertissements

  • Lors du choix de l'URL LDAP, l'attribut à utiliser pour l'authentification doit aussi être valide pour le fichier des utilisateurs de mod_authn_file. A cette fin, l'UID est idéal.
  • Lorsqu'ils ajoutent des utilisateurs via FrontPage, les administrateurs de FrontPage doivent choisir des noms d'utilisateurs qui existent déjà dans l'annuaire LDAP (pour des raisons évidentes). De même, le mot de passe que l'administrateur entre dans le formulaire est ignoré, car pour l'authentification, Apache utilise le mot de passe de l'annuaire LDAP, et non le mot de passe enregistré dans le fichier des utilisateurs, ce qui peut semer la confusion parmi les administrateurs web.
  • Pour supporter FrontPage, Apache doit être compilé avec mod_auth_basic, mod_authn_file et mod_authz_groupfile. Ceci est dû au fait qu'Apache doit utiliser le fichier de groupes de mod_authz_groupfile pour déterminer le niveau d'accès d'un utilisateur au site web FrontPage.
  • Les directives doivent être placées dans les fichiers .htaccess. Elles ne fonctionneront pas si vous les placez dans une section <Location> ou <Directory>. Ceci est dû au fait que pour savoir où se trouve la liste des utilisateurs valides, mod_authnz_ldap doit être en mesure d'atteindre la directive AuthGroupFile qui se trouve dans les fichiers .htaccess de FrontPage. Si les directives de mod_authnz_ldap ne sont pas situées dans le même fichier .htaccess que les directives FrontPage, la configuration ne fonctionnera pas, car mod_authnz_ldap ne sera jamais en mesure de traiter le fichier .htaccess, et par conséquent ne pourra jamais trouver le fichier des utilisateurs géré par FrontPage.

Directive AuthLDAPAuthorizePrefix

Description: | Spécifie le préfixe ajouté aux variables d'environnement durant la phase d'autorisation
Syntaxe: | AuthLDAPAuthorizePrefix préfixe
Défaut: | AuthLDAPAuthorizePrefix AUTHORIZE_
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible depuis la version 2.3.6

Cette directive permet de spécifier le préfixe ajouté aux variables d'environnement durant la phase d'autorisation. Si la valeur spécifiée est AUTHENTICATE_, les utilisateurs de ces variables d'environnement verront les mêmes informations, que le serveur effectue une authentification, une autorisation, ou les deux.

Note

Aucune variable d'autorisation n'est définie lorsqu'un utilisateur s'est vu autoriser l'accès via la directive Require valid-user.

Directive AuthLDAPBindAuthoritative

Description: | Détermine si l'on doit utiliser d'autres fournisseurs d'authentification lorsque le serveur ne peut pas valider les données d'authentification de l'utilisateur, alors que ce dernier possède un DN.
Syntaxe: | AuthLDAPBindAuthoritative off|on
Défaut: | AuthLDAPBindAuthoritative on
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Par défaut, des fournisseurs d'authentification sont appelés si un utilisateur ne possède pas de DN, mais ne le sont pas si l'utilisateur possède un DN et si son mot de passe ne peut pas être vérifié lors d'une connexion au serveur LDAP. Si la directive AuthLDAPBindAuthoritative est définie à off, d'autres modules d'authentification configurés auront une chance de valider le mot de passe de l'utilisateur si la tentative de connexion au serveur LDAP échoue pour une raison quelconque (avec les données d'authentification fournies).

Ceci permet aux utilisateurs présent à la fois dans l'annuaire LDAP et dans un fichier AuthUserFile de s'authentifier lorsque le serveur LDAP est disponible, alors que le compte de l'utilisateur est verrouillé ou que son mot de passe est inutilisable pour une raison quelconque.

Voir aussi

  • AuthUserFile
  • AuthBasicProvider

Directive AuthLDAPBindDN

Description: | Un DN optionnel pour se connecter au serveur LDAP
Syntaxe: | AuthLDAPBindDN dn
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Cette directive permet de définir un DN optionnel pour se connecter au serveur afin d'y rechercher des entrées. Si aucun DN n'est spécifié, mod_authnz_ldap tentera une connexion anonyme.

Directive AuthLDAPBindPassword

Description: | Mot de passe à utiliser en conjonction avec le DN de connexion
Syntaxe: | AuthLDAPBindPassword mot-de-passe
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | exec: est disponible depuis la version 2.4.5 du serveur HTTP Apache.

Cette directive permet de spécifier un mot de passe à utiliser en conjonction avec le DN de connexion. Notez que ce mot de passe constitue en général une donnée sensible, et doit donc être protégé de manière appropriée. Vous ne devez utiliser les directives AuthLDAPBindDN et AuthLDAPBindPassword que si vous en avez vraiment besoin pour effectuer une recherche dans l'annuaire.

Si la valeur spécifiée débute par "exec:", la commande qui suit sera exécutée, et la première ligne renvoyée par la commande sur la sortie standard sera utilisée comme mot de passe.

# Mot de passe spécifié directement
AuthLDAPBindPassword secret

# Exécution de /path/to/program pour obtenir le mot de passe
AuthLDAPBindPassword exec:/path/to/program

# Exécution de /path/to/otherProgram avec un argument pour obtenir le mot de passe
AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"

Directive AuthLDAPCharsetConfig

Description: | Chemin du fichier de configuration de la correspondance langage/jeu de caractères
Syntaxe: | AuthLDAPCharsetConfig chemin-fichier
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_authnz_ldap

La directive AuthLDAPCharsetConfig permet de définir le chemin du fichier de configuration de la correspondance langage/jeu de caractères. chemin-fichier est un chemin relatif au répertoire défini par la directive ServerRoot. Ce fichier contient une liste de correspondances extension de langage/jeu de caractères. La plupart des administrateurs utilisent le fichier charset.conv fourni qui associe les extensions de langage courantes à leurs jeux de caractères.

Le fichier contient des lignes au format suivant :

extension de langage jeu de caractères [Nom du langage] ...

L'extension est insensible à la casse. Les lignes vides et les lignes commençant par un dièse (#) sont ignorées.

Directive AuthLDAPCompareAsUser

Description: | Utilisation des données d'authentification de l'utilisateur pour effectuer les comparaisons pour l'attribution des autorisations
Syntaxe: | AuthLDAPCompareAsUser on|off
Défaut: | AuthLDAPCompareAsUser off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible depuis la version version 2.3.6

Lorsque cette directive est définie, et si mod_authnz_ldap a authentifié l'utilisateur, les recherches LDAP pour les autorisations utilisent le nom distinctif trouvé (DN) et le mot de passe d'authentification basique HTTP de l'utilisateur authentifié au lieu des données d'authentification configurées au niveau du serveur.

Les vérifications d'autorisation ldap-attribute, ldap-user, et ldap-group (niveau simple seulement) utilisent des comparaisons.

Cette directive n'a d'effet sur les comparaisons effectuées au cours des traitements de groupe imbriqués, et lorsque la directive AuthLDAPSearchAsUser est aussi activée.

Cette directive ne doit être utilisée que si votre serveur LDAP n'autorise pas les recherches anonymes, ou si vous ne pouvez pas utiliser de nom d'utilisateur dédié via la directive AuthLDAPBindDN.

Voir aussi

  • AuthLDAPInitialBindAsUser
  • AuthLDAPSearchAsUser

Directive AuthLDAPCompareDNOnServer

Description: | Utilise le serveur LDAP pour comparer les DNs
Syntaxe: | AuthLDAPCompareDNOnServer on|off
Défaut: | AuthLDAPCompareDNOnServer on
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Lorsque cette directive est définie à on, mod_authnz_ldap utilise le serveur LDAP pour comparer les DNs. Il s'agit de la seule méthode infaillible pour comparer les DNs. mod_authnz_ldap va rechercher dans l'annuaire le DN spécifié par la directive Require dn, puis extraire ce DN et le comparer avec le DN extrait de l'entrée de l'utilisateur. Si cette directive est à off, mod_authnz_ldap effectue une simple comparaison de chaînes. Cette dernière approche peut produire des faux négatifs, mais elle est beaucoup plus rapide. Notez cependant que le cache de mod_ldap peut accélérer la comparaison de DNs dans la plupart des situations.

Directive AuthLDAPDereferenceAliases

Description: | À quel moment le module va déréférencer les alias
Syntaxe: | AuthLDAPDereferenceAliases never|searching|finding|always
Défaut: | AuthLDAPDereferenceAliases always
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Cette directive permet de spécifier à quel moment mod_authnz_ldap va déréférencer les alias au cours des opérations liées à LDAP. La valeur par défaut est always.

Directive AuthLDAPGroupAttribute

Description: | L'attribut LDAP utilisé pour vérifier l'appartenance d'un utilisateur à un groupe.
Syntaxe: | AuthLDAPGroupAttribute attribut
Défaut: | AuthLDAPGroupAttribute member uniquemember
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Cette directive permet de spécifier quel attribut LDAP est utilisé pour vérifier l'appartenance d'un utilisateur à un groupe. On peut spécifier plusieurs attributs en répétant cette directive plusieurs fois. Si la directive n'est pas définie, mod_authnz_ldap utilise les attributs member et uniquemember.

Directive AuthLDAPGroupAttributeIsDN

Description: | Utilise le DN de l'utilisateur pour vérifier son appartenance à un groupe
Syntaxe: | AuthLDAPGroupAttributeIsDN on|off
Défaut: | AuthLDAPGroupAttributeIsDN on
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Lorsqu'elle est définie à on, cette directive indique que c'est le DN de l'utilisateur qui doit être utilisé pour vérifier son appartenance à un groupe. Dans le cas contraire, c'est le nom de l'utilisateur qui sera utilisé. Par exemple, supposons que le client envoie le nom d'utilisateur bjenson, qui correspond au DN LDAP cn=Babs Jenson,o=Example. Si la directive est à on, mod_authnz_ldap va vérifier si cn=Babs Jenson, o=Example est un membre du groupe. Dans le cas contraire, mod_authnz_ldap vérifiera si bjenson est un membre du groupe.

Directive AuthLDAPInitialBindAsUser

Description: | Détermine si le serveur effectue la recherche initiale du DN en utilisant le nom propre de l'utilisateur pour l'authentification de base et non de manière anonyme, ou en utilisant des données d'authentification codées en dur pour le serveur
Syntaxe: | AuthLDAPInitialBindAsUser off|on
Défaut: | AuthLDAPInitialBindAsUser off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible depuis la version 2.3.6

Par défaut, le serveur convertit le nom d'utilisateur pour l'authentification de base en nom distinctif LDAP (DN) soit de manière anonyme, soit avec un couple nom/mot de passe dédié. Cette directive permet de forcer le serveur à utiliser les véritables nom d'utilisateur et mot de passe fournis par l'utilisateur pour effectuer la recherche initiale du DN.

Si le nom d'utilisateur ne peut pas s'authentifier directement et nécessite de légères modifications, voir la directive AuthLDAPInitialBindPattern.

Cette directive ne doit être utilisée que si votre serveur LDAP n'autorise pas les recherches anonymes, ou si vous ne pouvez pas utiliser de nom d'utilisateur dédié via la directive AuthLDAPBindDN.

Non disponible dans la cas d'une autorisation seule

On ne peut utiliser cette directive que si ce module effectue une authentification, et n'a aucun effet si ce module n'est utilisé que pour les processus d'autorisation.

Voir aussi

  • AuthLDAPInitialBindPattern
  • AuthLDAPBindDN
  • AuthLDAPCompareAsUser
  • AuthLDAPSearchAsUser

Directive AuthLDAPInitialBindPattern

Description: | Spécifie la modification a apporter au nom d'utilisateur pour l'authentification de base lors de l'authentification auprès du serveur LDAP pour effectuer une recherche de DN
Syntaxe: | AuthLDAPInitialBindPattern regex substitution
Défaut: | AuthLDAPInitialBindPattern (.*) $1 (nom de l'utilisateur distant utilisé tel quel)
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible depuis la version 2.3.6

Si la directive AuthLDAPInitialBindAsUser est définie à ON, le nom utilisateur pour l'authentification de base sera transformé selon l'expression rationnelle regex et l'argument substitution spécifiés.

L'expression rationnelle est comparée au nom d'utilisateur pour l'authentification de base courant. L'argument substitution peut contenir des références arrières, mais n'effectue aucune autre interpolation de variable.

Cette directive ne doit être utilisée que si votre serveur LDAP n'autorise pas les recherches anonymes, ou si vous ne pouvez pas utiliser de nom d'utilisateur dédié via la directive AuthLDAPBindDN.

AuthLDAPInitialBindPattern (.+) $1@example.com
AuthLDAPInitialBindPattern (.+) cn=$1,dc=example,dc=com

Non disponible dans la cas d'une autorisation seule

On ne peut utiliser cette directive que si ce module effectue une authentification, et n'a aucun effet si ce module n'est utilisé que pour les processus d'autorisation.

Débogage

Le DN de substitution est enregistré dans la variable d'environnement LDAP_BINDASUSER. Si l'expression rationnelle ne convient pas, le nom d'utilisateur est utilisé tel quel.

Voir aussi

  • AuthLDAPInitialBindAsUser
  • AuthLDAPBindDN

Directive AuthLDAPMaxSubGroupDepth

Description: | Spécifie la profondeur d'imbrication des sous-groupes maximale prise en compte avant l'abandon de la recherche de l'utilisateur.
Syntaxe: | AuthLDAPMaxSubGroupDepth Nombre
Défaut: | AuthLDAPMaxSubGroupDepth 10
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible à partir de la version 2.3.0 du serveur HTTP Apache

Lorsque cette directive est définie à une valeur X non nulle, en combinaison avec l'utilisation de la directive Require ldap-group DN-groupe, les données de connexion fournies seront utilisées pour vérifier l'appartenance de l'utilisateur à l'objet de l'annuaire DN-groupe ou à tout sous-groupe du groupe courant en tenant compte de la profondeur d'imbrication maximale X spécifiée par la directive.

Se référer à la section Require ldap-group pour un exemple plus détaillé.

Performances dans le cas des groupes imbriqués

Lorsque les directives AuthLDAPSubGroupAttribute et AuthLDAPGroupAttribute se recouvrent (comme c'est le cas par défaut et requis par les schémas LDAP courants), la recherche de sous-groupes au sein de grands groupes peut être très longue. Si vos groupes sont très grands et non imbriqués, définissez la directive AuthLDAPMaxSubGroupDepth à 0.

Directive AuthLDAPRemoteUserAttribute

Description: | Spécifie l'attribut dont la valeur renvoyée au cours de la requête de l'utilisateur sera utilisée pour définir la variable d'environnement REMOTE_USER
Syntaxe: | AuthLDAPRemoteUserAttribute uid
Défaut: | none
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Lorsque cette directive est définie, la variable d'environnement REMOTE_USER sera définie à la valeur de l'attribut spécifié. Assurez-vous que cet attribut soit bien inclus dans la liste d'attributs spécifiés dans la définition de AuthLDAPUrl ; dans le cas contraire, cette directive n'aurait aucun effet. Si elle est présente, cette directive l'emporte sur AuthLDAPRemoteUserIsDN. Elle peut s'avérer utile par exemple, si vous souhaitez que les utilisateurs se connectent à un site web en utilisant leur adresse email, alors qu'une application sous-jacente nécessite un nom d'utilisateur comme identifiant.

Directive AuthLDAPRemoteUserIsDN

Description: | Utilise le DN de l'utilisateur pour définir la variable d'environnement REMOTE_USER
Syntaxe: | AuthLDAPRemoteUserIsDN on|off
Défaut: | AuthLDAPRemoteUserIsDN off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Lorsque cette directive est à on, la variable d'environnement REMOTE_USER sera définie avec la valeur du DN complet de l'utilisateur authentifié, et non plus avec simplement le nom d'utilisateur fourni par le client. Elle est définie à off par défaut.

Directive AuthLDAPSearchAsUser

Description: | Utilise les données d'authentification de l'utilisateur pour la recherche des autorisations
Syntaxe: | AuthLDAPSearchAsUser on|off
Défaut: | AuthLDAPSearchAsUser off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible depuis la version 2.3.6

Lorsque cette directive est définie, et si mod_authnz_ldap a authentifié l'utilisateur, les recherches LDAP pour définir les autorisations utilisent le nom distinctif (DN) trouvé et le mot de passe pour l'authentification de base HTTP de l'utilisateur authentifié, au lieu des données d'authentification configurées au niveau du serveur.

Les vérifications d'autorisation ldap-filter et ldap-dn utilisent des recherches.

Cette directive n'a d'effet sur les comparaisons effectuées au cours des traitements de groupe imbriqués, et lorsque la directive AuthLDAPCompareAsUser est aussi activée.

Cette directive ne doit être utilisée que si votre serveur LDAP n'autorise pas les recherches anonymes, ou si vous ne pouvez pas utiliser de nom d'utilisateur dédié via la directive AuthLDAPBindDN.

Voir aussi

  • AuthLDAPInitialBindAsUser
  • AuthLDAPCompareAsUser

Directive AuthLDAPSubGroupAttribute

Description: | Spécifie les noms d'attribut, un par directive, utilisés pour différencier les membres du groupe courant qui sont eux-mêmes des groupes.
Syntaxe: | AuthLDAPSubGroupAttribute attribut
Défaut: | AuthLDAPSubgroupAttribute member uniquemember
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible à partir de la version 2.3.0 du serveur HTTP Apache

Un objet groupe LDAP peut contenir des membres qui sont des utilisateurs et des membres qui sont eux-mêmes des groupes (appelés sous-groupes ou groupes imbriqués). La directive AuthLDAPSubGroupAttribute spécifie l'attribut utilisé pour identifier les groupes, alors que la directive AuthLDAPGroupAttribute spécifie l'attribut utilisé pour identifier les utilisateurs. On peut spécifier plusieurs attributs en répétant la directive plusieurs fois. Si elle n'est pas définie, mod_authnz_ldap utilise les attributs member et uniqueMember.

Directive AuthLDAPSubGroupClass

Description: | Spécifie quelles valeurs d'objectClass LDAP identifient les objets de l'annuaire qui sont des groupes au cours du traitement des sous-groupes.
Syntaxe: | AuthLDAPSubGroupClass ObjectClass-LDAP
Défaut: | AuthLDAPSubGroupClass groupOfNames groupOfUniqueNames
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap
Compatibilité: | Disponible à partir de la version 2.3.0 du serveur HTTP Apache

Un objet groupe LDAP peut contenir des membres qui sont des utilisateurs et des membres qui sont eux-mêmes des groupes (appelés sous-groupes ou groupes imbriqués). La directive AuthLDAPSubGroupAttribute permet d'identifier les membres qui sont des sous-groupes du groupe courant (à l'opposé des membres utilisateurs). La directive AuthLDAPSubGroupClass permet de spécifier les valeurs d'objectClass LDAP utilisées pour vérifier que certains membres sont en fait des objets groupe. Les sous-groupes ainsi identifiés peuvent alors faire l'objet d'une recherche d'autres membres utilisateurs ou sous-groupes. On peut spécifier plusieurs attributs en répétant cette directive plusieurs fois. Si cette directive n'est pas définie, mod_authnz_ldap utilise les attributs groupOfNames et groupOfUniqueNames.

Directive AuthLDAPUrl

Description: | L'URL permettant de spécifier les paramètres de la recherche LDAP
Syntaxe: | AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS]
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authnz_ldap

Une URL conforme à la RFC 2255 qui permet de spécifier les paramètres à utiliser pour la recherche dans l'annuaire LDAP. La syntaxe de l'URL est :

ldap://hôte:port/DN-de-base?attribut?portée?filtre

Si vous souhaitez mettre à la disposition d'Apache plusieurs URLs LDAP, la syntaxe sera :

AuthLDAPUrl "ldap://ldap1.example.com ldap2.example.com/dc=..."

Mise en garde : Si vous spécifiez plusieurs serveurs, vous devez en entourer la liste avec des guillemets ; dans le cas contraire, vous générerez une erreur : "AuthLDAPURL takes one argument, URL to define LDAP connection..". Vous pouvez bien entendu ajouter des paramètres de recherche à chacun des serveurs spécifiés.

ldap
Pour ldap non sécurisé, utilisez la chaîne ldap. Pour ldap sécurisé, utilisez à la place la chaîne ldaps. LDAP sécurisé n'est disponible que si Apache a été lié avec une bibliothèque LDAP supportant SSL.
hôte:port

Il s'agit du nom/port du serveur ldap (dont la valeur par défaut est localhost:389 pour ldap, et localhost:636 pour ldaps). Pour spécifier plusieurs serveurs LDAP redondants, indiquez simplement leur liste en les séparant par des espaces. mod_authnz_ldap tentera alors de se connecter à chacun des serveurs jusqu'à ce qu'il parvienne à se connecter avec succès. Notez qu'en cas de multiples serveurs LDAP, l'ensemble de l'URL LDAP doit être entourée de guillemets.

lorsqu'une connection a été établie avec un serveur, elle reste active pendant toute la durée de vie du processus httpd, ou jusqu'à ce que le serveur LDAP cesse de fonctionner.

Si le serveur LDAP cesse de fonctionner, et ainsi interrompt une connexion existante, mod_authnz_ldap tentera de se reconnecter en commençant par le premier serveur de la liste, et ainsi de suite avec les serveurs redondants suivants. Notez que ce processus n'a rien à voir avec une véritable recherche de type round-robin.

DN-de-base
Le DN de la branche de l'annuaire à partir de laquelle toutes les recherches seront lancées. Il doit au moins correspondre à la racine de votre annuaire, mais vous pouvez aussi indiquer une branche plus spécifique.
attribut
Il s'agit de l'attribut à utiliser pour la recherche. Bien que la RFC 2255 autorise une liste d'attributs séparés par des virgules, seul le premier sera retenu, sans tenir compte des autres attributs fournis. Si aucun attribut n'est fourni, l'attribut par défaut est uid. Il est judicieux de choisir un attribut dont la valeur sera unique parmi toutes les entrées de la branche de l'annuaire que vous aurez définie. Tous les attributs spécifiés seront enregistrés dans des variables d'environnement avec le préfixe AUTHENTICATE_, afin de pouvoir être utilisés par d'autres modules.
portée
Il s'agit de la portée de la recherche. Elle peut prendre les valeurs one ou sub. Notez que la RFC 2255 supporte aussi une portée de valeur base, mais cette dernière n'est pas supportée par le module. Si la portée n'est pas définie, ou si elle est définie à base, c'est la valeur de portée par défaut sub qui sera utilisée.
filtre
Il s'agit d'un filtre de recherche LDAP valide. Si aucun filtre n'est spécifié, le filtre par défaut (objectClass=*) sera utilisé, ce qui corrspond à une recherche de tous les types d'objets de l'arborescence. La taille des filtres est limitée à environ 8000 caractères (valeur de la macro MAX_STRING_LEN dans le code source d'Apache), ce qui s'avère plus que suffisant pour la plupart des applications. Depuis la version 2.4.10, il est possible d'utiliser le paramètre none pour spécifier qu'aucun filtre n'est activé ; ce paramètre est obligatoire avec certains serveurs LDAP primitifs.

Pour une recherche, les attribut, filtre et nom d'utilisateur fournis par le client HTTP sont combinés pour créer un filtre de recherche du style : (&(filtre)(attribut =nom-utilisateur)).

Par exemple, considérons l'URL ldap://ldap.example.com/o=Example?cn?sub?(posixid=*). Lorsqu'un client tentera de se connecter en utilisant le nom d'utilisateur Babs Jenson, le filtre de recherche sera : (&(posixid=*)(cn=Babs Jenson)).

On peut encore ajouter un paramètre optionnel pour permettre à l'URL LDAP de surcharger le type de connexion. Ce paramètre peut prendre l'une des valeurs suivantes :

NONE
Établit une connexion non sécurisée sur le port LDAP par défaut, ce qui est équivalent à ldap:// sur le port 389.
SSL
Établit une connexion sécurisée sur le port LDAP sécurisé par défaut, ce qui est équivalent à ldaps://.
TLS | STARTTLS
Établit une connexion sécurisée par élévation de niveau sur le port LDAP par défaut. Cette connexion sera initialisée sur le port 389 par défaut, puis élevée à un niveau de connexion sécurisée sur le même port.

Voir plus haut pour des exemples d'URLs définies par la directive AuthLDAPUrl.


mod_authz_core - Serveur Apache HTTP Version 2.4

Module Apache mod_authz_core

Description: | Autorisation basique
Statut: | Base
Identificateur de Module: | authz_core_module
Fichier Source: | mod_authz_core.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache HTTPD

Sommaire

Ce module fournit des fonctionnalités d'autorisation basiques permettant d'accorder ou refuser l'accès à certaines zones du site web aux utilisateurs authentifiés. mod_authz_core donne la possibilité d'enregistrer divers fournisseurs d'autorisation. Il est en général utilisé avec un module fournisseur d'authentification comme mod_authn_file, et un module d'autorisation comme mod_authz_user. Il permet aussi l'application d'une logique élaborée au déroulement du processus d'autorisation.

Création des alias du fournisseur d'autorisation

Il est possible de créer des fournisseurs d'autorisation étendus dans le fichier de configuration et de leur assigner un nom d'alias. On peut ensuite utiliser ces fournisseurs aliasés dans une directive Require de la même manière qu'on le ferait pour des fournisseurs d'autorisation de base. En plus de la possibilité de créer et d'aliaser un fournisseur étendu, le même fournisseur d'autorisation étendu peut être référencé par plusieurs localisations.

Exemple

Dans l'exemple suivant, on crée deux alias de fournisseur d'autorisation ldap différents basés sur le fournisseur d'autorisation ldap-group. Il est ainsi possible pour un seul répertoire de vérifier l'appartenance à un groupe dans plusieurs serveurs ldap :

<AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx>
    AuthLDAPBindDN cn=youruser,o=ctx
    AuthLDAPBindPassword yourpassword
    AuthLDAPURL ldap://ldap.host/o=ctx
</AuthzProviderAlias>

<AuthzProviderAlias ldap-group ldap-group-alias2 cn=my-other-group,o=dev>
    AuthLDAPBindDN cn=yourotheruser,o=dev
    AuthLDAPBindPassword yourotherpassword
    AuthLDAPURL ldap://other.ldap.host/o=dev?cn
</AuthzProviderAlias>

Alias "/secure" "/webpages/secure"
<Directory "/webpages/secure">
    Require all granted

    AuthBasicProvider file

    AuthType Basic
    AuthName LDAP_Protected_Place

    #implied OR operation
    Require ldap-group-alias1
    Require ldap-group-alias2
</Directory>

Conteneurs d'autorisation

Les directives de conteneur d'autorisation <RequireAll>, <RequireAny> et <RequireNone> peuvent être combinées entre elles et avec la directive Require pour confectionner une logique d'autorisation complexe.

L'exemple ci-dessous illustre la logique d'autorisation suivante. Pour pouvoir accéder à la ressource, l'utilisateur doit être l'utilisateur superadmin, ou appartenir aux deux groupes LDAP admins et Administrateurs et soit appartenir au groupe ventes ou avoir ventes comme valeur de l'attribut LDAP dept. De plus, pour pouvoir accéder à la ressource, l'utilisateur ne doit appartenir ni au groupe temps, ni au groupe LDAP Employés temporaires.

<Directory "/www/mydocs">
    <RequireAll>
        <RequireAny>
            Require user superadmin
            <RequireAll>
            Require group admins
            Require ldap-group cn=Administrators,o=Airius
                <RequireAny>
                Require group sales
                Require ldap-attribute dept="sales"
                </RequireAny>
            </RequireAll>
        </RequireAny>
        <RequireNone>
            Require group temps
            Require ldap-group cn=Temporary Employees,o=Airius
        </RequireNone>
    </RequireAll>
</Directory>

Les directives Require

Le module mod_authz_core met à disposition des fournisseurs d'autorisation génériques utilisables avec la directive Require.

Require env

Le fournisseur env permet de contrôler l'accès au serveur en fonction de l'existence d'une variable d'environnement. Lorsque Require env env-variable est spécifié, la requête se voit autoriser l'accès si la variable d'environnement env-variable existe. Le serveur permet de définir facilement des variables d'environnement en fonction des caractéristiques de la requête du client via les directives fournies par le module mod_setenvif. Cette directive Require env permet donc de contrôler l'accès en fonction des valeurs des en-têtes de la requête HTTP tels que User-Agent (type de navigateur), Referer, entre autres.

SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
<Directory "/docroot">
    Require env let_me_in
</Directory>

Avec cet exemple, les navigateurs dont la chaîne user-agent commence par KnockKnock/2.0 se verront autoriser l'accès, alors que tous les autres seront rejetés.

Lorsque le serveur cherche un chemin via une sous-requête interne (par exemple la recherche d'un DirectoryIndex), ou lorsqu'il génère un listing du contenu d'un répertoire via le module mod_autoindex, la sous-requête n'hérite pas des variables d'environnement spécifiques à la requête. En outre, à cause des phases de l'API auxquelles mod_setenvif prend part, les directives SetEnvIf ne sont pas évaluées séparément dans la sous-requête.

Require all

Le fournisseur all reproduit la fonctionnalité précédemment fournie par les directives 'Allow from all' et 'Deny from all'. Il accepte un argument dont les deux valeurs possibles sont : 'granted' ou 'denied'. Les exemples suivants autorisent ou interdisent l'accès à toutes les requêtes.

Require all granted
Require all denied

Require method

Le fournisseur method permet d'utiliser la méthode HTTP dans le processus d'autorisation. Les méthodes GET et HEAD sont ici considérées comme équivalentes. La méthode TRACE n'est pas supportée par ce fournisseur ; utilisez à la place la directive TraceEnable.

Dans l'exemple suivant, seules les méthodes GET, HEAD, POST, et OPTIONS sont autorisées :

Require method GET POST OPTIONS

Dans l'exemple suivant, les méthodes GET, HEAD, POST, et OPTIONS sont autorisées sans authentification, alors que toutes les autres méthodes nécessitent un utilisateur valide :

<RequireAny>
     Require method GET POST OPTIONS
     Require valid-user
</RequireAny>

Require expr

Le fournisseur expr permet d'accorder l'autorisation d'accès de base en fonction d'expressions arbitraires.

Require expr "%{TIME_HOUR} -ge 9 && %{TIME_HOUR} -le 17"
<RequireAll>
    Require expr "!(%{QUERY_STRING} =~ /secret/)"
    Require expr "%{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"
</RequireAll>
Require expr "!(%{QUERY_STRING} =~ /secret/) && %{REQUEST_URI} in { '/example.cgi', '/other.cgi' }"

La syntaxe de l'expression est décrite dans la documentation de ap_expr.

Normalement, l'expression est évaluée avant l'authentification. Cependant, si l'expression renvoie false et se réfère à la variable %{REMOTE_USER}, le processus d'authentification sera engagé et l'expression réévaluée.

Directive AuthMerging

Description: | Définit la manière dont chaque logique d'autorisation des sections de configuration se combine avec celles des sections de configuration précédentes.
Syntaxe: | AuthMerging Off | And | Or
Défaut: | AuthMerging Off
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authz_core

Lorsque l'autorisation est activée, elle est normalement héritée par chaque section de configuration suivante, à moins qu'un jeu de directives d'autorisations différent ne soit spécifié. Il s'agit du comportement par défaut, qui correspond à la définition explicite AuthMerging Off.

Dans certaines situations cependant, il peut être souhaitable de combiner la logique d'autorisation d'une section de configuration avec celle de la section précédente lorsque les sections de configuration se combinent entre elles. Dans ce cas, deux options sont disponibles, And et Or.

Lorsqu'une section de configuration contient AuthMerging And ou AuthMerging Or, sa logique d'autorisation se combine avec celle de la section de configuration qui la précède (selon l'ordre général des sections de configuration), et qui contient aussi une logique d'autorisation, comme si les deux sections étaient concaténées respectivement dans une directive <RequireAll> ou <RequireAny>.

La définition de la directive AuthMerging ne concerne que la section de configuration dans laquelle elle apparaît. Dans l'exemple suivant, seuls les utilisateurs appartenant au groupe alpha sont autorisés à accéder à /www/docs. Les utilisateurs appartenant au groupe alpha ou au groupe beta sont autorisés à accéder à /www/docs/ab. Cependant, la définition implicite à Off de la directive AuthMerging s'applique à la section de configuration <Directory> concernant le répertoire /www/docs/ab/gamma, ce qui implique que les directives d'autorisation de cette section l'emportent sur celles des sections précédentes. Par voie de conséquence, seuls les utilisateurs appartenant au groupe gamma sont autorisés à accéder à /www/docs/ab/gamma.
<Directory "/www/docs">
    AuthType Basic
    AuthName Documents
    AuthBasicProvider file
    AuthUserFile "/usr/local/apache/passwd/passwords"
    Require group alpha
</Directory>

<Directory "/www/docs/ab">
    AuthMerging Or
    Require group beta
</Directory>

<Directory "/www/docs/ab/gamma">
    Require group gamma
</Directory>

Directive <AuthzProviderAlias>

Description: | Regroupe des directives représentant une extension d'un fournisseur d'autorisation de base qui pourra être référencée à l'aide de l'alias spécifié
Syntaxe: | <AuthzProviderAlias fournisseur-de-base Alias Paramètres-Require> ... </AuthzProviderAlias>
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_authz_core

Les balises <AuthzProviderAlias> et </AuthzProviderAlias> permettent de regrouper des directives d'autorisation auxquelles on pourra faire référence à l'aide de l'alias spécifié dans une directive Require.

Directive AuthzSendForbiddenOnFailure

Description: | Envoie '403 FORBIDDEN' au lieu de '401 UNAUTHORIZED' si l'authentification réussit et si l'autorisation a été refusée.
Syntaxe: | AuthzSendForbiddenOnFailure On|Off
Défaut: | AuthzSendForbiddenOnFailure Off
Contexte: | répertoire, .htaccess
Statut: | Base
Module: | mod_authz_core
Compatibilité: | Disponible depuis la version 2.3.11 d'Apache HTTPD

Par défaut, si l'authentification réussit, alors que l'autorisation est refusée, Apache HTTPD renvoie un code de réponse HTTP '401 UNAUTHORIZED'. En général, les navigateurs proposent alors une nouvelle fois à l'utilisateur la boîte de dialogue de saisie du mot de passe, ce qui n'est pas toujours souhaitable. La directive AuthzSendForbiddenOnFailure permet de changer le code de réponse en '403 FORBIDDEN'.

Avertissement de sécurité

La modification de la réponse en cas de refus d'autorisation diminue la sécurité du mot de passe, car elle indique à un éventuel attaquant que le mot de passe qu'il a saisi était correct.

Directive Require

Description: | Vérifie si un utilisateur authentifié a une autorisation d'accès accordée par un fournisseur d'autorisation.
Syntaxe: | Require [not] nom-entité [nom-entité] ...
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authz_core

Cette directive permet de vérifier si un utilisateur authentifié a l'autorisation d'accès accordée pour un certain fournisseur d'autorisation et en tenant compte de certaines restrictions. mod_authz_core met à disposition les fournisseurs d'autorisation génériques suivants :

Require all granted
L'accès est autorisé sans restriction.
Require all denied
L'accès est systématiquement refusé.
Require env env-var [env-var] ...
L'accès n'est autorisé que si l'une au moins des variables d'environnement spécifiées est définie.
Require method http-method [http-method] ...
L'accès n'est autorisé que pour les méthodes HTTP spécifiées.
Require expr expression
L'accès est autorisé si expression est évalué à vrai.

Voici quelques exemples de syntaxes autorisées par mod_authz_user, mod_authz_host et mod_authz_groupfile :

Require user identifiant utilisateur [identifiant utilisateur] ...
Seuls les utilisateurs spécifiés auront accès à la ressource.
Require group nom groupe [nom groupe] ...
Seuls les utilisateurs appartenant aux groupes spécifiés auront accès à la ressource.
Require valid-user
Tous les utilisateurs valides auront accès à la ressource.
Require ip 10 172.20 192.168.2
Les clients dont les adresses IP font partie des tranches spécifiées auront accès à la ressource.

D'autres modules d'autorisation comme mod_authnz_ldap, mod_authz_dbm, mod_authz_dbd, mod_authz_owner et mod_ssl implémentent des options de la directive Require.

Pour qu'une configuration d'authentification et d'autorisation fonctionne correctement, la directive Require doit être accompagnée dans la plupart des cas de directives AuthName, AuthType et AuthBasicProvider ou AuthDigestProvider, ainsi que de directives telles que AuthUserFile et AuthGroupFile (pour la définition des utilisateurs et des groupes). Exemple :

AuthType Basic
AuthName "Restricted Resource"
AuthBasicProvider file
AuthUserFile "/web/users"
AuthGroupFile "/web/groups"
Require group admin

Les contrôles d'accès appliqués de cette manière sont effectifs pour toutes les méthodes. C'est d'ailleurs ce que l'on souhaite en général. Si vous voulez n'appliquer les contrôles d'accès qu'à certaines méthodes, tout en laissant les autres méthodes sans protection, placez la directive Require dans une section <Limit>.

Le résultat de la directive Require peut être inversé en utilisant l'option not. Comme dans le cas de l'autre directive d'autorisation inversée <RequireNone>, si la directive Require est inversée, elle ne peut qu'échouer ou produire un résultat neutre ; elle ne peut donc alors pas autoriser une requête de manière indépendante.

Dans l'exemple suivant, tous les utilisateurs appartenant aux groupes alpha et beta ont l'autorisation d'accès, à l'exception de ceux appartenant au groupe reject.

<Directory "/www/docs">
    <RequireAll>
        Require group alpha beta
        Require not group reject
    </RequireAll>
</Directory>

Lorsque plusieurs directives Require sont placées dans une même section de configuration, et ne se trouvent pas dans une autre directive d'autorisation comme <RequireAll>, elles sont implicitement contenues dans une directive <RequireAny>. Ainsi, la première directive Require qui autorise l'accès à un utilisateur autorise l'accès pour l'ensemble de la requête, et les directives Require suivantes sont ignorées.

Avertissement à propos de la sécurité

Prettez une attention particulière aux directives d'autorisation définies au sein des sections Location qui se chevauchent avec des contenus servis depuis le système de fichiers. Par défaut, les configurations définies dans ces sections l'emportent sur les configurations d'autorisations définies au sein des sections Directory et Files sections.

La directive AuthMerging permet de contrôler la manière selon laquelle les configurations d'autorisations sont fusionnées au sein des sections précitées.

Voir aussi

  • Tutoriel du contrôle d'accès
  • Conteneurs d'autorisation
  • mod_authn_core
  • mod_authz_host

Directive <RequireAll>

Description: | Regroupe plusieurs directives d'autorisation dont aucune ne doit échouer et dont au moins une doit retourner un résultat positif pour que la directive globale retourne elle-même un résultat positif.
Syntaxe: | <RequireAll> ... </RequireAll>
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authz_core

Les balises <RequireAll> et </RequireAll> permettent de regrouper des directives d'autorisation dont aucune ne doit échouer, et dont au moins une doit retourner un résultat positif pour que la directive <RequireAll> retourne elle-même un résultat positif.

Si aucune des directives contenues dans la directive <RequireAll> n'échoue, et si au moins une retourne un résultat positif, alors la directive <RequireAll> retourne elle-même un résultat positif. Si aucune ne retourne un résultat positif, et si aucune n'échoue, la directive globale retourne un résultat neutre. Dans tous les autres cas, elle échoue.

Voir aussi

  • Conteneurs d'autorisation
  • Authentification, autorisation et contrôle d'accès

Directive <RequireAny>

Description: | Regroupe des directives d'autorisation dont au moins une doit retourner un résultat positif pour que la directive globale retourne elle-même un résultat positif.
Syntaxe: | <RequireAny> ... </RequireAny>
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authz_core

Les balises <RequireAny> et </RequireAny> permettent de regrouper des directives d'autorisation dont au moins une doit retourner un résultat positif pour que la directive <RequireAny> retourne elle-même un résultat positif.

Si une ou plusieurs directives contenues dans la directive <RequireAny> retournent un résultat positif, alors la directive <RequireAny> retourne elle-même un résultat positif. Si aucune ne retourne un résultat positif et aucune n'échoue, la directive globale retourne un résultat neutre. Dans tous les autres cas, elle échoue.

Comme les directives d'autorisation inversées sont incapables de retourner un résultat positif, elles ne peuvent pas impacter de manière significative le résultat d'une directive <RequireAny> (elles pourraient tout au plus faire échouer la directive dans le cas où elles échoueraient elles-mêmes, et où toutes les autres directives retourneraient un résultat neutre). C'est pourquoi il n'est pas permis d'utiliser les directives d'autorisation inversées dans une directive <RequireAny>.

Voir aussi

  • Conteneurs d'autorisation
  • Authentification, autorisation et contrôle d'accès

Directive <RequireNone>

Description: | Regroupe des directives d'autorisation dont aucune ne doit retourner un résultat positif pour que la directive globale n'échoue pas.
Syntaxe: | <RequireNone> ... </RequireNone>
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authz_core

Les balises <RequireNone> et </RequireNone> permettent de regrouper des directives d'autorisation dont aucune ne doit retourner un résultat positif pour que la directive <RequireNone> n'échoue pas.

Si une ou plusieurs directives contenues dans la directive <RequireNone> retournent un résultat positif, la directive <RequireNone> échouera. Dans tous les autres cas, cette dernière retournera un résultat neutre. Ainsi, comme pour la directive d'autorisation inversée Require not, elle ne peut jamais autoriser une requête de manière indépendante car elle ne pourra jamais retourner un résultat positif. Par contre, on peut l'utiliser pour restreindre l'ensemble des utilisateurs autorisés à accéder à une ressource.

Comme les directives d'autorisation inversées sont incapables de retourner un résultat positif, elles ne peuvent pas impacter de manière significative le résultat d'une directive <RequireNone>. C'est pourquoi il n'est pas permis d'utiliser les directives d'autorisation inversées dans une directive <RequireNone>.

Voir aussi

  • Conteneurs d'autorisation
  • Authentification, autorisation et contrôle d'accès


mod_authz_dbd - Serveur Apache HTTP Version 2.4

Module Apache mod_authz_dbd

Description: | Autorisation en groupe et reconnaissance d'identité avec base SQL
Statut: | Extension
Identificateur de Module: | authz_dbd_module
Fichier Source: | mod_authz_dbd.c
Compatibilité: | Disponible dans les versions 2.4 et supérieures d'Apache

Sommaire

Ce module fournit des fonctionnalités d'autorisation permettant d'accorder ou de refuser aux utilisateurs authentifiés l'accès à certaines zones du site web en fonction de leur appartenance à tel ou tel groupe. Les modules mod_authz_groupfile et mod_authz_dbm fournissent une fonctionnalité similaire, mais ici le module interroge une base de données SQL pour déterminer si un utilisateur appartient ou non à tel ou tel groupe.

Ce module propose également des fonctionnalités de connexion utilisateur s'appuyant sur une base de données, ce qui peut se révéler particulièrement utile lorsque le module est utilisé conjointement avec mod_authn_dbd.

Ce module s'appuie sur mod_dbd pour spécifier le pilote de la base de données sous-jacente et les paramètres de connexion, et gérer les connexions à la base de données.

Traitement des bugs

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

Voir aussi

  • Require
  • AuthDBDUserPWQuery
  • DBDriver
  • DBDParams

Les directives Require

Les directives Require d'Apache permettent, au cours de la phase d'autorisation, de s'assurer qu'un utilisateur est bien autorisé à accéder à une ressource. mod_authz_dbd ajoute les types d'autorisation dbd-group, dbd-login et dbd-logout.

A partir de la version 2.4.8, les directives require DBD supportent les expressions.

Require dbd-group

Cette directive permet de spécifier à quel groupe un utilisateur doit appartenir pour obtenir l'autorisation d'accès.

Require dbd-group team
AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"

Require dbd-login

Cette directive permet de spécifier une requête à exécuter pour indiquer que l'utilisateur s'est authentifié.

Require dbd-login
AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

Require dbd-logout

Cette directive permet de spécifier une requête à exécuter pour indiquer que l'utilisateur s'est déconnecté.

Require dbd-logout
AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"

Reconnaissance d'identité s'appuyant sur une base de données

Outre sa fonction d'autorisation standard consistant à vérifier l'appartenance à des groupes, ce module permet aussi de gérer des sessions utilisateur côté serveur grâce à sa fonctionnalité de connexion utilisateur en s'appuyant sur une base de données. En particulier, il peut mettre à jour le statut de session de l'utilisateur dans la base de données chaque fois que celui-ci visite certaines URLs (sous réserve bien entendu que l'utilisateur fournissent les informations de connexion nécessaires).

Pour cela, il faut definir deux directives Require spéciales : Require dbd-login et Require dbd-logout. Pour les détails de leur utilisation, voir l'exemple de configuration ci-dessous.

Reconnaissance d'identité côté client

Certains administrateurs peuvent vouloir implémenter une gestion de session côté client fonctionnant de concert avec les fonctionnalités de connexion/déconnexion des utilisateurs côté serveur offertes par ce module, en définissant ou en annulant par exemple un cookie HTTP ou un jeton similaire lorsqu'un utilisateur se connecte ou se déconnecte.

Pour supporter une telle intégration, mod_authz_dbd exporte un programme à déclenchement optionnel (hook) qui sera lancé chaque fois que le statut d'un utilisateur sera mis à jour dans la base de données. D'autres modules de gestion de session pourront alors utiliser ce programme pour implémenter des fonctions permettant d'ouvrir et de fermer des sessions côté client.

Exemple de configuration

# configuration de mod_dbd
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache pass=xxxxxx"

DBDMin  4
DBDKeep 8
DBDMax  20
DBDExptime 300

<Directory "/usr/www/mon.site/team-private/">
  # configuration de mod_authn_core et mod_auth_basic
  # pour mod_authn_dbd
  AuthType Basic
  AuthName Team
  AuthBasicProvider dbd

  # requête SQL de mod_authn_dbd pour authentifier un utilisateur qui se
  # connecte
  AuthDBDUserPWQuery \
    "SELECT password FROM authn WHERE user = %s AND login = 'true'"

  # configuration de mod_authz_core pour mod_authz_dbd
  Require dbd-group team

  # configuration de mod_authz_dbd
  AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"

  # lorsqu'un utilisateur échoue dans sa tentative d'authentification ou
  # d'autorisation, on l'invite à se connecter ; cette page doit
  # contenir un lien vers /team-private/login.html
  ErrorDocument 401 "/login-info.html"

  <Files "login.html">
    # il n'est pas nécessaire que l'utilisateur soit déjà connecté !
    AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"

    # le processus de connexion dbd exécute une requête pour enregistrer
    # la connexion de l'utilisateur
    Require dbd-login
    AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

    # redirige l'utilisateur vers la page d'origine (si elle existe)
    # après une connexion réussie
    AuthzDBDLoginToReferer On
  </Files>

  <Files "logout.html">
    # le processus de déconnexion dbd exécute une requête pour
    # enregistrer la déconnexion de l'utilisateur
    Require dbd-logout
    AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
  </Files>
</Directory>

Directive AuthzDBDLoginToReferer

Description: | Définit si le client doit être redirigé vers la page d'origine en cas de connexion ou de déconnexion réussie si un en-tête de requête Referer est présent
Syntaxe: | AuthzDBDLoginToReferer On|Off
Défaut: | AuthzDBDLoginToReferer Off
Contexte: | répertoire
Statut: | Extension
Module: | mod_authz_dbd

Utilisée en conjonction avec Require dbd-login ou Require dbd-logout, cette directive permet de rediriger le client vers la page d'origine (l'URL contenue dans l'en-tête de requête HTTP Referer, s'il est présent). En l'absence d'en-tête Referer, la définition AuthzDBDLoginToReferer On sera ignorée.

Directive AuthzDBDQuery

Description: | Définit la requête SQL pour l'opération requise
Syntaxe: | AuthzDBDQuery requête
Contexte: | répertoire
Statut: | Extension
Module: | mod_authz_dbd

La directive AuthzDBDQuery permet de spécifier une requête SQL à exécuter. Le but de cette requête dépend de la directive Require en cours de traitement.

  • Avec la directive Require dbd-group, elle spécifie une requête permettant de rechercher les groupes d'appartenance de l'utilisateur courant. Ceci correspond à la fonctionnalité standard d'autres modules d'autorisation comme mod_authz_groupfile et mod_authz_dbm. La première colonne de chaque enregistrement renvoyé par la requête doit contenir une chaîne de caractères correspondant à un nom de groupe. La requête peut renvoyer zéro, un ou plusieurs enregistrements.
    Require dbd-group
AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"
  • Avec la directive Require dbd-login ou Require dbd-logout, elle ne refusera jamais l'accès, mais au contraire exécutera une requête SQL permettant d'enregistrer la connexion ou la déconnexion de l'utilisateur. Ce dernier doit être déjà authentifié avec mod_authn_dbd.
    Require dbd-login
AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

Dans tous les cas, l'identifiant utilisateur sera transmis comme paramètre sous la forme d'une simple chaîne lorsque la requête SQL sera exécutée. Il y sera fait référence dans la requête en utilisant le spécificateur de format %s.

Directive AuthzDBDRedirectQuery

Description: | Définit une requête pour rechercher une page vers laquelle rediriger l'utilisateur après une connexion réussie
Syntaxe: | AuthzDBDRedirectQuery requête
Contexte: | répertoire
Statut: | Extension
Module: | mod_authz_dbd

Spécifie une requête SQL optionnelle à utiliser après une connexion (ou une déconnexion) réussie pour rediriger l'utilisateur vers une URL, qui peut être spécifique à l'utilisateur. L'identifiant utilisateur sera transmis comme paramètre sous la forme d'une simple chaîne lorsque la requête SQL sera exécutée. Il y sera fait référence dans la requête en utilisant le spécificateur de format %s.

AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"

La première colonne du premier enregistrement renvoyé par la requête doit contenir une chaîne de caractères correspondant à une URL vers laquelle rediriger le client. Les enregistrements suivants sont ignorés. Si aucun enregistrement n'est renvoyé, le client ne sera pas redirigé.

Notez que AuthzDBDLoginToReferer l'emporte sur cette directive si les deux sont définies.


mod_authz_dbm - Serveur Apache HTTP Version 2.4

Module Apache mod_authz_dbm

Description: | Autorisation basée sur les groupes à l'aide de fichiers DBM
Statut: | Extension
Identificateur de Module: | authz_dbm_module
Fichier Source: | mod_authz_dbm.c
Compatibilité: | Disponible depuis les versions 2.1 et supérieures d'Apache

Sommaire

Ce module permet d'autoriser ou d'interdire l'accès à certaines zones du site web aux utilisateurs authentifiés en fonction de leur appartenance à un groupe spécifié. Le module mod_authz_groupfile fournit une fonctionnalité similaire.

Traitement des bugs

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

Voir aussi

  • Require

The Require Directives

Les directives Require d'Apache permettent, au cours de la phase d'autorisation, de s'assurer qu'un utilisateur est bien autorisé à accéder à une ressource. mod_authz_dbm ajoute les types d'autorisation dbm-group et dbm-file-group.

A partir de la version 2.4.8, les directives require DBM supportent les expressions.

Require dbm-group

Cette directive permet de spécifier à quel groupe un utilisateur doit appartenir pour obtenir l'autorisation d'accès.

Require dbm-group admin

Require dbm-file-group

Lorsque cette directive est définie, l'utilisateur doit appartenir au groupe du fichier pour pouvoir y accéder.

Require dbm-file-group

Exemple d'utilisation

Notez que si vous utilisez mod_authz_dbm, le mot-clé pour les groupes d'authentification qui était auparavant group est maintenant dbm-group :

<Directory "/foo/bar">
  AuthType Basic
  AuthName "Secure Area"
  AuthBasicProvider dbm
  AuthDBMUserFile "site/data/users"
  AuthDBMGroupFile "site/data/users"
  Require dbm-group admin
</Directory>

Directive AuthDBMGroupFile

Description: | Définit le nom du fichier de base de données contenant la liste des groupes d'utilisateurs permettant de définir les autorisations des utilisateurs
Syntaxe: | AuthDBMGroupFile chemin-fichier
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authz_dbm

La directive AuthDBMGroupFile sert à définir le nom d'un fichier DBM contenant la liste des groupes d'utilisateurs. Les utilisateurs peuvent dès lors se voir autoriser ou refuser leurs accès selon l'appartenance à tel ou tel groupe. chemin-fichier est le chemin absolu du fichier de groupes.

La clé du fichier de groupes est le nom d'utilisateur. La valeur de chaque clé est la liste des groupes, séparés par des virgules, auxquels l'utilisateur appartient. Cette liste ne doit comporter ni espace, ni caractère ':'.

Sécurité

Le fichier spécifié par la directive AuthDBMGroupFile doit être situé en dehors de l'arborescence des documents du serveur web. Ne le placez surtout pas dans le répertoire qu'il protège, faute de quoi, les clients pourraient le télécharger, en l'abscence de protection supplémentaire.

Utilisation combinée de fichiers DBM de groupes et de mots de passe : dans certains cas, il est plus simple de gérer une seule base de données contenant les groupes et mots de passe de chaque utilisateur. L'écriture de programmes de support en est ainsi simplifiée car ils n'ont plus qu'un seul fichier DBM à gérer et à verrouiller. Pour ce faire, on attribue le même nom de fichier DBM aux fichiers de groupes et de mots de passe :

AuthDBMGroupFile "/www/userbase"
AuthDBMUserFile "/www/userbase"

La clé du fichier DBM unique est le nom d'utilisateur. La valeur associée à la clé contient :

Mot de passe chiffré : Liste de groupes [ : (ignoré) ]

La partie mot de passe contient comme d'habitude le mot de passe chiffré. Viennent ensuite le caractère ':' et la liste des groupes séparés par des virgules. Il est possible d'ajouter d'autres données en fin de ligne après un autre caractère ':', mais elles seront ignorées par le module d'autorisation. Il s'agit du format utilisé par www.telescope.org pour sa base de données combinée groupes et mots de passe.

Directive AuthzDBMType

Description: | Définit le type de fichier de base de données contenant la liste des groupes d'utilisateurs
Syntaxe: | AuthzDBMType default|SDBM|GDBM|NDBM|DB
Défaut: | AuthzDBMType default
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_authz_dbm

Définit le type de fichier de base de données contenant la liste des groupes d'utilisateurs. Le type de base de données par défaut est déterminé à la compilation. Les autres types de bases de données disponibles dépendent aussi de la configuration de la compilation.

Quel que soit le programme que vous utilisez pour créer votre fichier de groupes, il est impératif que celui-ci soit configuré pour utiliser le même type de base de données.


mod_authz_groupfile - Serveur Apache HTTP Version 2.4

Module Apache mod_authz_groupfile

Description: | Autorisation basée sur les groupes à l'aide de fichiers textes
Statut: | Base
Identificateur de Module: | authz_groupfile_module
Fichier Source: | mod_authz_groupfile.c
Compatibilité: | Disponible depuis les versions 2.1 et supérieures d'Apache

Sommaire

Ce module permet d'autoriser ou d'interdire l'accès à certaines zones du site web aux utilisateurs authentifiés en fonction de leur appartenance à un groupe spécifié. Le module mod_authz_dbm fournit une fonctionnalité similaire.

Traitement des bugs

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

Voir aussi

  • Require

Les directives Require

Les directives Require d'Apache permettent, au cours de la phase d'autorisation, de s'assurer qu'un utilisateur est bien autorisé à accéder à une ressource. mod_authz_groupfile ajoute les types d'autorisation group et file-group.

A partir de la version 2.4.8, les directives require groupfile supportent les expressions.

Require group

Cette directive permet de spécifier à quel groupe un utilisateur doit appartenir pour obtenir l'autorisation d'accès.

Require group admin

Require file-group

Lorsque cette directive est définie, Les permissions système du fichier auquel on veut accéder sont vérifiées. L'utilisateur doit être un membre d'un groupe de même nom que le groupe qui possède le fichier. Voir mod_authz_owner pour plus de détails.

Require file-group

Directive AuthGroupFile

Description: | Définit le nom d'un fichier texte contenant la liste des groupes d'utilisateurs permettant de définir les autorisations des utilisateurs
Syntaxe: | AuthGroupFile chemin-fichier
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Base
Module: | mod_authz_groupfile

La directive AuthGroupFile permet de définir le nom d'un fichier texte contenant la liste des groupes d'utilisateurs. L'appartenance d'un utilisateur à tel ou tel groupe pourra dès lors être utilisée pour définir les permissions d'accès de l'utilisateur. chemin-fichier est le chemin du fichier de groupes. S'il n'est pas absolu, ce chemin est considéré comme relatif au répertoire défini par la directive ServerRoot.

Chaque ligne du fichier de groupes contient un nom de groupe suivi du caractère ':' et des noms des utilisateurs membres du groupe séparés par des espaces.

Exemple :

mon-groupe : bob joe anne

Notez que la recherche dans de grands fichiers textes est très inefficace ; la directive AuthDBMGroupFile fournit de bien meilleures performances.

Sécurité

Le fichier AuthGroupFile ne doit pas être stocké dans l'arborescence des documents du site web ; ne le placez surtout pas dans le répertoire qu'il protège, faute de quoi les clients pourraient le télécharger.


mod_authz_host - Serveur Apache HTTP Version 2.4

Module Apache mod_authz_host

Description: | Autorisations de groupe basées sur l'hôte (nom ou adresse IP)
Statut: | Base
Identificateur de Module: | authz_host_module
Fichier Source: | mod_authz_host.c
Compatibilité: | Le fournisseur forward-dns est disponible à partir de la version 2.4.19 du serveur HTTP Apache

Sommaire

Les fournisseurs d'autorisation implémentés par le module mod_authz_host sont enregistrés à l'aide de la directive Require. On peut utiliser cette directive à l'intérieur de sections <Directory>, <Files>, ou <Location> ou de fichiers .htaccess pour contrôler l'accès à certaines zones du serveur. Le contrôle d'accès peut être effectué en fonction du nom d'hôte ou de l'adresse IP.

En général, les directives de restriction d'accès s'appliquent à toutes les méthodes d'accès (GET, PUT, POST, etc...). C'est d'ailleurs ce que l'on souhaite dans la plupart des cas. Il est cependant possible de ne restreindre l'accès que pour certaines méthodes, tout en laissant les autres méthodes sans protection, en plaçant les directives dans une section <Limit>.

Traitement des bugs

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

Voir aussi

  • Authentification, autorisation et contrôle d'accès
  • Require

Les directives Require

La directive Apache Require est utilisée au cours de la phase d'autorisation pour vérifier si un utilisateur se voit accorder ou refuser l'accès à une ressource. mod_authz_host fournit les types d'autorisation ip, host, forward-dns et local. D'autres types d'autorisation sont aussi disponibles, mais nécessitent le chargement des modules d'autorisation appropriés.

Ces fournisseurs d'autorisation permettent de déterminer quels hôtes peuvent accéder à une zone du serveur. On peut contrôler l'accès en fonction du nom d'hôte, de l'adresse IP, ou d'un intervalle d'adresses IP.

A partir de la version 2.4.8, les directives require host supportent les expressions.

Require ip

Le fournisseur ip permet de contrôler l'accès au serveur en fonction de l'adresse IP du client distant. Lorsque Require ip adresse-ip est spécifié, la requête est autorisée si l'adresse IP du client distant correspond à

Une adresse IP complète :

Require ip 10.1.2.3
Require ip 192.168.1.104 192.168.1.205

L'adresse IP d'un hôte pour qui l'accès est accordé

Une adresse IP partielle :

Require ip 10.1
Require ip 10 172.20 192.168.2

Les 1 à 3 premiers octets d'une adresse IP, pour une restriction à un sous-réseau.

Une paire réseau/masque de sous-réseau :

Require ip 10.1.0.0/255.255.0.0

Un réseau a.b.c.d, et un masque de sous-réseau w.x.y.z. pour une restriction de sous-réseau plus fine.

Une spécification CIDR réseau/nnn :

Require ip 10.1.0.0/16

Identique au cas précédent, excepté que le masque de sous-réseau représente les nnn premiers bits de poids fort.

Notez que les trois derniers exemples correspondent exectement au même ensemble d'hôtes.

On peut spécifier des adresses et des sous-réseaux IPv6 comme suit :

Require ip 2001:db8::a00:20ff:fea7:ccea
Require ip 2001:db8:1:1::a
Require ip 2001:db8:2:1::/64
Require ip 2001:db8:3::/48

Note: comme les adresses IP sont lues au démarrage, les expressions ne sont pas évaluées au moment de la requête.

Require host

Le fournisseur host permet de contrôler l'accès au serveur en fonction du nom d'hôte du client distant. Lorsque Require host nom-hôte est spécifié, la requête est autorisée si le nom d'hôte correspond à

Un nom de domaine (éventuellement partiel)

Require host example.org
Require host .net example.edu

Les hôtes dont les noms correspondent ou se terminent par la chaîne spécifiée se voient accorder l'accès. Seuls les élément de nom de domaine complets sont mis en correspondance ; ainsi, l'exemple ci-dessus correspondra à foo.example.org, mais ne correspondra pas à fooexample.org. Avec cette configuration, Apache va effectuer une double recherche DNS sur l'adresse IP du client, sans tenir compte de la définition de la directive HostnameLookups. Il va effectuer une recherche DNS inverse sur l'adresse IP pour trouver le nom d'hôte associé, puis une recherche DNS directe sur le nom d'hôte pour vérifier qu'il correspond bien à l'adresse IP originale. L'accès ne sera accordé que si le nom d'hôte correspond et si les recherches DNS inverse et directe sont cohérentes.

Require forward-dns

Le fournisseur forward-dns permet d'accéder au serveur sécurisé en fonction de simples noms d'hôte. Lorsque Require forward-dns host-name est spécifié, toute adresse IP correspondant à host-name se voit autoriser l'accès.

A la différence du fournisseur host, ce fournisseur n'effectue pas de recherche DNS inverse : il effectue simplement une requête DNS directe pour le nom d'hôte spécifié et donne accès au client si son adresse IP correspond. Il ne fonctionnera donc qu'avec des noms d'hôte, et non avec des noms de domaine. Par contre, comme le DNS inverse n'est pas sollicité, il fonctionnera avec des clients qui utilisent un service de DNS dynamique.

Require forward-dns bla.example.org

Un client dont l'adresse IP correspond au nom d'hôte bla.example.org se verra autoriser l'accès.

Require local

Le fournisseur local autorise l'accès au serveur si l'une au moins de ces conditions est satisfaite :

  • l'adresse IP du client correspond à 127.0.0.0/8
  • l'adresse IP du client est ::1
  • les adresses IP du client et du serveur sont identiques

L'exemple suivant montre une méthode simple pour sélectionner les connexions en provenance de l'hôte local :

Require local

Note concernant la sécurité

Si le contenu de votre serveur est mandaté, vous devez garder à l'esprit que l'adresse client correspondra à l'adresse de votre serveur mandataire et non à l'adresse du client, et l'utilisation de la directive Require dans ce contexte ne provoquera pas forcément l'effet désiré. Voir mod_remoteip pour une solution possible à ce problème.


mod_authz_owner - Serveur Apache HTTP Version 2.4

Module Apache mod_authz_owner

Description: | Autorisation basée sur l'appartenance des fichiers
Statut: | Extension
Identificateur de Module: | authz_owner_module
Fichier Source: | mod_authz_owner.c
Compatibilité: | Disponible depuis les versions 2.1 et supérieures d'Apache

Sommaire

Ce module permet de contrôler l'accès aux fichiers en comparant l'identifiant utilisateur ayant servi à l'authentification HTTP (l'identifiant utilisateur web) avec le propriétaire ou le groupe du fichier demandé du point de vue du système de fichiers. Le nom d'utilisateur et le mot de passe doivent déjà avoir été vérifiés par un module d'authentification comme mod_auth_basic ou mod_auth_digest. mod_authz_owner reconnaît deux arguments pour la directive Require : file-owner et file-group :

file-owner
Le nom d'utilisateur web utilisé pour l'authentification doit correspondre au nom système du propriétaire du fichier demandé. En d'autres termes, si le système indique jones comme propriétaire du fichier demandé, le nom d'utilisateur fourni pour l'authentification HTTP doit aussi être jones.
file-group
Le nom du groupe système du fichier demandé doit être présent dans une base de données de groupes fournie, par exemple, par mod_authz_groupfile ou mod_authz_dbm, et le nom d'utilisateur web fourni pour l'authentification doit être un membre de ce groupe. Par exemple, si le système indique que le groupe (système) du fichier demandé est accounts, le groupe accounts doit apparaître dans la base de données des groupes, et le nom d'utilisateur web utilisé pour l'authentification doit être un membre de ce groupe.

Note

Si le module mod_authz_owner est utilisé pour vérifier l'autorisation d'accès à une ressource qui n'est pas vraiment présente dans le système de fichiers (en d'autres termes une ressource virtuelle), il refusera l'accès.

En particulier, il n'accordera jamais l'accès à une ressource du type "Vues multiples" (MultiViews) d'un contenu négocié.

Traitement des bugs

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

Voir aussi

  • Require

Exemples de configuration

Require file-owner

Considérons un serveur Web Apache fonctionnant sous un système multi-utilisateurs, où les fichiers de chaque utilisateur sont stockés dans ~/public_html/private. En supposant qu'il n'existe qu'une seule base de données contenant les noms d'utilisateurs web, et que ces noms d'utilisateurs correspondent aux noms d'utilisateurs système qui sont les propriétaires effectifs des fichiers, la configuration de l'exemple suivant n'accordera l'autorisation d'accès aux fichiers qu'à leur propriétaire. L'utilisateur jones ne sera pas autorisé à accéder aux fichiers situés dans /home/smith/public_html/private, à moins que leur propriétaire ne soit jones au lieu de smith.

<Directory "/home/*/public_html/private">
    AuthType Basic
    AuthName MyPrivateFiles
    AuthBasicProvider dbm
    AuthDBMUserFile "/usr/local/apache2/etc/.htdbm-all"
    Require file-owner
</Directory>

Require file-group

Considérons un système similaire à celui décrit ci-dessus, mais où certains utilisateurs partagent leurs fichiers de projets dans ~/public_html/project-foo. Le groupe système des fichiers est foo, et il n'existe qu'une seule base de données AuthDBMGroupFile qui contient tous les noms d'utilisateurs web et leurs groupes d'appartenance. Ces noms d'utilisateurs web doivent alors appartenir au moins au groupe foo. En d'autres termes, si jones et smith sont tous deux membres du groupe foo, ils seront autorisés à accéder aux répertoires project-foo de chacun d'entre eux.

<Directory "/home/*/public_html/project-foo">
    AuthType Basic
    AuthName "Project Foo Files"
    AuthBasicProvider dbm

    # combined user/group database
    AuthDBMUserFile  "/usr/local/apache2/etc/.htdbm-all"
    AuthDBMGroupFile "/usr/local/apache2/etc/.htdbm-all"

    Satisfy All
    Require file-group
</Directory>


mod_authz_user - Serveur Apache HTTP Version 2.4

Module Apache mod_authz_user

Description: | Autorisation basée sur l'utilisateur
Statut: | Base
Identificateur de Module: | authz_user_module
Fichier Source: | mod_authz_user.c
Compatibilité: | Disponible depuis les versions 2.1 et supérieures d'Apache

Sommaire

Ce module permet d'accorder ou de refuser l'accès à certaines zones du site web aux utilisateurs authentifiés. mod_authz_user accorde l'accès si l'utilisateur authentifié fait partie de la liste spécifiée par une directive Require user. On peut aussi utiliser la directive Require valid-user pour accorder l'accès à tous les utilisateurs qui ont été authentifiés avec succès.

Traitement des bugs

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

Voir aussi

  • Require

The Require Directives

Les directives Require d'Apache permettent, au cours de la phase d'autorisation, de s'assurer qu'un utilisateur est bien autorisé à accéder à une ressource. mod_authz_user ajoute les types d'autorisation user et valid-user.

A partir de la version 2.4.8, les directives require DBM supportent les expressions.

Require user

Cette directive permet de spécifier une liste d'utilisateurs autorisés à accéder à la ressource.

Require user john paul george ringo

Require valid-user

Lorsque cette directive est définie, tout utilisateur qui s'est authentifié avec succès aura l'autorisation d'accès à la ressource.

Require valid-user

Copyright 2018 The Apache Software Foundation.
Autorisé sous Apache License, Version 2.0.


mod_autoindex - Serveur Apache HTTP Version 2.4

Module Apache mod_autoindex

Description: | Génère automatiquement des index de répertoires d'une manière similaire à la commande Unix ls, ou à la commande shell Win32 dir
Statut: | Base
Identificateur de Module: | autoindex_module
Fichier Source: | mod_autoindex.c

Sommaire

L'index d'un répertoire peut être généré de deux manières :

  • Un fichier situé dans ce répertoire, en général appelé index.html, mais dont le nom de ce ou ces fichiers peut être défini par la directive DirectoryIndex. C'est le module mod_dir qui traite alors cet index.
  • Un listing généré par le serveur, dont le format est contrôlé par un certain nombre de directives. Les directives AddIcon, AddIconByEncoding et AddIconByType permettent de définir une liste d'icônes à afficher en fonction des différents types de fichiers ; pour chaque fichier listé, le premier icône qui correspond au type du fichier est affiché. C'est le module mod_autoindex qui traite alors cet index.

Les deux fonctions sont séparées, si bien que vous pouvez entièrement supprimer (ou remplacer) la génération automatique d'index, si vous le souhaitez.

On active la génération automatique d'index en spécifiant Options +Indexes. Voir la directive Options pour plus de détails.

Si la directive IndexOptions est spécifiée avec l'option FancyIndexing, les en-têtes de colonnes sont des liens qui permettent de contrôler l'ordre de tri de l'affichage. Si vous actionnez le lien d'un en-tête, le listing sera généré à nouveau, trié en fonction des valeurs de la colonne concernée. Si l'on actionne de manière répétitive le même en-tête, l'ordre de tri est commuté entre les ordres croissant et décroissant. On peut supprimer ces liens d'en-têtes de colonnes à l'aide de l'option SuppressColumnSorting de la directive IndexOptions.

Notez que lorsque l'affichage est trié en fonction de la taille, c'est la taille réelle qui est prise en compte, et non la valeur affichée - ainsi, un fichier de 1010 octets sera toujours affiché avant un fichier de 1011 octets (en ordre croissant), même si la taille affichée des deux fichiers est "1K".

Arguments de la requête d'autoindexation

La chaîne de paramètres de la requête peut contenir de nombreux arguments permettant dans une certaine mesure au client de contrôler l'ordre de l'index du répertoire, ainsi que la liste des fichiers à afficher. Si vous souhaitez désactiver cette fonctionnalité, utilisez l'option IndexOptions IgnoreClient.

Les en-têtes de tri des colonnes eux-mêmes sont des hyper-liens auto-référant qui ajoutent les options de tri à la requête énumérées ci-dessous qui peuvent être ajoutées à toute requête concernant la ressource répertoire.

  • C=N trie l'affichage en fonction du nom de fichier
  • C=M trie l'affichage en fonction de la date de dernière modification, puis du nom de fichier
  • C=S trie l'affichage en fonction de la taille, puis du nom de fichier
  • C=D trie l'affichage en fonction de la description, puis du nom de fichier
  • O=A trie l'affichage selon l'ordre croissant
  • O=D trie l'affichage selon l'ordre décroissant
  • F=0 affiche le listing sous la forme d'une simple liste (sans FancyIndex)
  • F=1 affiche le listing avec en-têtes de colonnes sous forme de liens hyper-textes (FancyIndexed)
  • F=2 affiche le listing sous forme de table HTML avec en-têtes de colonnes contenant des liens hyper-textes (FancyIndexed)
  • V=0 désactive le tri en fonction de la version
  • V=1 active le tri en fonction de la version
  • P=modèle n'affiche que les fichiers correspondant au modèle spécifié

Notez que l'argument 'P' (pour Pattern) n'est testé qu'après que les directives habituelles IndexIgnore ont été traitées, et que tous les noms de fichiers sont encore assujettis aux mêmes critères que pour tout autre listing auto-indexé. L'interpréteur d'arguments de requête de mod_autoindex s'arrête immédiatement s'il rencontre une option non reconnue. Les arguments de requête doivent être bien formés, selon la table ci-dessus.

Les options de requêtes sont illustrées par l'exemple ci-dessous, qui peut être copié et collé dans un fichier header.html. Notez que l'argument inconnu "X", pour le bouton submit, est introduit en dernier afin de s'assurer que tous les arguments ont été interprétés avant que mod_autoindex ne rencontre l'entrée X=Go.

      <form action="" method="get">
Montre moi une <select name="F">
<option value="0"> liste simple</option>
<option value="1" selected="selected"> liste avec
      en-têtes</option>
<option value="2"> liste avec en-tête sous forme de
      table</option>
</select>
triée par <select name="C">
<option value="N" selected="selected"> nom</option>
<option value="M"> date de modification</option>
<option value="S"> taille</option>
<option value="D"> description</option>
</select>
<select name="O">
<option value="A" selected="selected"> croissant</option>
<option value="D"> décroissant</option>
</select>
<select name="V">
<option value="0" selected="selected"> dans l'ordre
      normal</option>
<option value="1"> en fonction de la version</option>
</select>
correspondant à <input type="text" name="P" value="*" />
<input type="submit" name="X" value="Go" />
</form>

Directive AddAlt

Description: | Texte optionnel à afficher à la place d'un icône pour un fichier en fonction de son nom
Syntaxe: | AddAlt texte fichier [fichier] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive AddAlt permet d'afficher un texte optionnel pour un fichier, à la place d'un icône, dans le cas d'un affichage FancyIndexing. fichier est une extension de fichier, un nom de fichier partiel, une expression avec caractères génériques ou un nom de fichier complet permettant de caractériser le(s) fichier(s) concerné(s). Si texte contient des espaces, vous devez l'entourer de guillemets ou d'apostrophes (" ou '). Ce texte optionnel sera affiché si le client ne peut pas afficher d'images, si le chargement d'images est désactivé ou si l'icône ne peut pas être trouvé.

AddAlt "PDF file" *.pdf
AddAlt Compressed *.gz *.zip *.Z

Directive AddAltByEncoding

Description: | Texte optionnel à afficher à la place d'un icône pour un fichier en fonction de son codage MIME
Syntaxe: | AddAltByEncoding texte codage MIME [codage MIME] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive AddAltByEncoding permet d'afficher un texte optionnel à la place d'un icône pour un fichier dans le cas d'un affichage FancyIndexing. codage MIME doit être un type valide, comme x-compress. Si texte contient des espaces, vous devez l'entourer de guillemets ou d'apostrophes (" ou '). Ce texte optionnel sera affiché si le client ne peut pas afficher d'images, si le chargement d'images est désactivé ou si l'icône ne peut pas être trouvé.

AddAltByEncoding gzip x-gzip

Directive AddAltByType

Description: | Texte optionnel à afficher à la place d'un icône pour un fichier en fonction de son type MIME
Syntaxe: | AddAltByType texte type MIME [type MIME] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive AddAltByType permet d'afficher un texte optionnel à la place d'un icône pour un fichier dans le cas d'un affichage FancyIndexing. type MIME doit être un type MIME valide, comme text/html. Si texte contient des espaces, vous devez l'entourer de guillemets ou d'apostrophes (" ou '). Ce texte optionnel sera affiché si le client ne peut pas afficher d'images, si le chargement d'images est désactivé ou si l'icône ne peut pas être trouvé.

AddAltByType 'Fichier texte' text/plain

Directive AddDescription

Description: | Afficher la description d'un fichier
Syntaxe: | AddDescription texte [fichier] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

Cette directive permet d'afficher une description pour un fichier, dans le cas d'un affichage FancyIndexing. fichier est une extension de fichier, un nom de fichier partiel, une expression avec caractères génériques ou un nom de fichier complet permettant de caractériser le fichier. texte doit être entouré de guillemets (").

AddDescription "The planet Mars" mars.gif
AddDescription "My friend Marshall" friends/mars.gif

La taille par défaut, habituelle du champ de description est de 23 octets. L'option IndexOptions SuppressIcon ajoute 6 octets, l'option IndexOptions SuppressSize en ajoute 7 et l'option IndexOptions SuppressLastModified en ajoute 19. Ainsi, la plus grande taille par défaut qui peut être assignée à la colonne description est de 55 octets.

Comme l'argument fichier peut être un nom de fichier partiel, vous devez garder à l'esprit qu'un nom de fichier partiel trop court pourra correspondre à des fichiers non voulus. Par exemple, le.html correspondra au fichier le.html, mais aussi au fichier example.html. En cas d'ambiguïté, utilisez un nom de fichier aussi complet que possible, et ordonnez votre liste de directives AddDescription en conséquence.

Voir le mot-clé DescriptionWidth de la directive module="mod_autoindex">IndexOptions pour plus de détails sur la manière d'augmenter la taille de cette colonne, ou pour permettre des descriptions de taille illimitée.

Avertissement

Le texte descriptif défini par la directive AddDescription peut contenir des marquages HTML, comme des balises ou des entités caractères. Si la limite de taille de la colonne description venait à tronquer une balise (par exemple couper la fin d'une phrase en caractères gras), le résultat pourrait en affecter toute la suite du listing du répertoire.

Arguments avec chemins

Les chemins absolus ne sont actuellement pas supportés et ne peuvent correspondre à aucun chemin réel à l'exécution. Les arguments contenant des chemins relatifs, qui ne devraient être normalement utilisés que dans les fichiers htaccess, sont implicitement préfixés par '*/' afin d'éviter toute association avec des noms de répertoires partiels.

Directive AddIcon

Description: | Icône à afficher pour un fichier en fonction de son nom
Syntaxe: | AddIcon icône nom [nom] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

Cette directive permet de déterminer l'icône à afficher à côté d'un fichier dont le nom se termine par nom, dans le cas d'un affichage FancyIndexing. icône est une URL relative (échappée par des caractères '%') vers l'icône, une URL distante pleinement qualifiée, ou de la forme (alttext,url), où alttext est le symbole texte correspondant à l'icône à afficher dans les navigateurs en mode texte.

nom correspond à ^^DIRECTORY^^ pour les répertoires, ^^BLANKICON^^ pour les lignes vides (pour personnaliser la présentation du listing), une extension de fichier, une expression avec caractères génériques, un nom de fichier partiel ou un nom de fichier complet.

^^BLANKICON^^ n'est utilisé que pour le formatage, et n'est donc pas nécessaire si vous utilisez IndexOptions HTMLTable.

#Examples
AddIcon (IMG,/icons/image.png) .gif .jpg .png
AddIcon /icons/dir.png ^^DIRECTORY^^
AddIcon /icons/backup.png *~

Lorsque c'est possible, il est préférable d'utiliser AddIconByType plutôt que AddIcon.

Directive AddIconByEncoding

Description: | Icône à afficher à côté d'un fichier en fonction de son codage MIME
Syntaxe: | AddIconByEncoding icône codage MIME [codage MIME] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

Cette directive permet de déterminer l'icône à afficher à côté d'un fichier dans le cas d'un affichage FancyIndexing. icône est une URL relative (échappée par des caractères '%') vers l'icône, une URL pleinement qualifiée, ou de la forme (alttext,url), où alttext est le symbole texte correspondant à l'icône à afficher dans les navigateurs en mode texte.

codage MIME doit être un codage valide, comme x-compress.

AddIconByEncoding /icons/compress.png x-compress

Directive AddIconByType

Description: | Icône à afficher à côté d'un fichier en fonction de son type MIME
Syntaxe: | AddIconByType icône type MIME [type MIME] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

Cette directive permet de déterminer l'icône à afficher à côté d'un fichier de type MIME type MIME dans le cas d'un affichage FancyIndexing. icône est une URL relative (échappée par des caractères '%') vers l'icône, une URL pleinement qualifiée, ou de la forme (alttext,url), où alttext est le symbole texte correspondant à l'icône à afficher dans les navigateurs en mode texte.

type MIME est une expression avec caractères génériques représentant le type MIME.

AddIconByType (IMG,/icons/image.png) image/*

Directive DefaultIcon

Description: | Icône à afficher par défaut lorsqu'aucun icône spécifique n'est précisé
Syntaxe: | DefaultIcon chemin URL
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive DefaultIcon permet de définir l'icône à afficher à côté d'un fichier lorsqu'aucun icône spécifique n'a été précisé, dans le cas d'un affichage FancyIndexing. chemin URL est une URL relative (échappée par des caractères '%') vers l'icône ou une URL pleinement qualifiée.

DefaultIcon /icon/unknown.png

Directive HeaderName

Description: | Nom du fichier qui sera inséré au début de la page contenant l'index
Syntaxe: | HeaderName nom fichier
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive HeaderName permet de définir le nom du fichier qui sera inséré au début de la page contenant l'index. nom fichier est le nom du fichier à inclure.

HeaderName HEADER.html

Les deux directives HeaderName et ReadmeName traitent maintenant nom fichier comme un chemin URI relatif au chemin utilisé pour accéder au répertoire faisant l'objet de l'index. Si nom fichier commence par un slash '/', il sera considéré comme relatif au répertoire défini par la directive DocumentRoot.

HeaderName /include/HEADER.html

nom fichier doit correspondre à un document dont le type MIME est du style text/* (par exemple text/html, text/plain, etc...). Cela signifie que nom fichier peut faire référence à un script CGI si le véritable type MIME du script (et non celui de sa sortie) est marqué comme text/html par exemple à l'aide d'une directive comme :

AddType text/html .cgi

Une négociation de contenu sera effectuée si Options MultiViews a été précisé. Si nom fichier correspond à un document statique text/html (et non à un script CGI), et une des deux options Includes ou IncludesNOEXEC est activée, le fichier sera traité en tant qu'inclusion côté serveur (Server Side Include) (voir la documentation de mod_include).

Si le fichier spécifié par la directive HeaderName contient les en-têtes d'un document HTML ((<html>, <head>, etc...), vous serez probablement amené à définir IndexOptions +SuppressHTMLPreamble, de manière à ce que ces balises ne soient pas répétées.

Voir aussi

  • ReadmeName

Directive IndexHeadInsert

Description: | Insère du texte dans la section HEAD de la page d'index.
Syntaxe: | IndexHeadInsert "marque ..."
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive IndexHeadInsert permet de spécifier une chaîne de caractères à insérer dans la section <head> du code HTML généré pour la page d'index.

IndexHeadInsert "<link rel=\"sitemap\" href=\"/sitemap.html\">"

Directive IndexIgnore

Description: | Ajouts à la liste des fichiers à cacher lors de l'affichage de l'index d'un répertoire
Syntaxe: | IndexIgnore fichier [fichier] ...
Défaut: | IndexIgnore "."
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive IndexIgnore permet d'effectuer des ajouts à la liste des fichiers à cacher lors de l'affichage de l'index d'un répertoire. fichier est une expression avec caractères génériques de style shell ou un nom de fichier complet. Plusieurs directives IndexIgnore effectuent des ajouts à la liste, et ne remplacent pas la liste des fichiers à ignorer. Par défaut, la liste contient . (le répertoire courant).

IndexIgnore .??* *~ *# HEADER* README* RCS CVS *,v *,t

Expressions rationnelles

Cette directive est actuellement incompatible avec les sections de configuration qui comportent des arguments avec expressions rationnelles comme <DirectoryMatch>

Directive IndexIgnoreReset

Description: | Vide la liste des fichiers à cacher lors de l'affichage du contenu d'un répertoire
Syntaxe: | IndexIgnoreReset ON|OFF
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex
Compatibilité: | Versions 2.3.10 et supérieures

La directive IndexIgnoreReset supprime toute liste de fichiers définie par la directive IndexIgnore et héritée par ailleurs d'autres sections de configuration.

<Directory "/var/www">
    IndexIgnore *.bak .??* *~ *# HEADER* README* RCS CVS *,v *,t
</Directory>
<Directory "/var/www/backups">
    IndexIgnoreReset ON
    IndexIgnore .??* *# HEADER* README* RCS CVS *,v *,t
</Directory>

Revoyez la configuration par défaut pour une liste de modèles que vous voulez ignorer explicitement après usage de cette directive.

Directive IndexOptions

Description: | Diverses options de configuration pour l'indexation d'un répertoire
Syntaxe: | IndexOptions [+|-]option [[+|-]option] ...
Défaut: | Par défaut, aucune option n'est activée.
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive IndexOptions permet de spécifier les options de configuration de l'indexation du répertoire. option peut prendre l'une des valeurs suivantes :

AddAltClass
Ajoute une déclaration de classe CSS supplémentaire à chaque enregistrement de la table du listing du répertoire dans le cas où IndexOptions HTMLTable est activé et où un IndexStyleSheet a été défini. Plutôt que d'appliquer à chaque enregistrement de la table les classes standards even et odd, c'est ici une classe even-ALT ou odd-ALT qui sera appliquée, où ALT sera soit le texte alternatif standard associé au style du fichier (par exemple snd, txt, img, etc...), soit le texte alternatif défini par une des différentes directives AddAlt*.
Charset=jeu de caractères (Versions 2.0.61 et supérieures du serveur HTTP Apache)
Le mot-clé Charset vous permet de spécifier le jeu de caractères de la page générée. La valeur par défaut est UTF-8 sous Windows et MAC OS X, et ISO-8859-1 dans les autres cas (en fait selon que le système de fichiers sous-jacent utilise les noms de fichiers en Unicode ou non).
IndexOptions Charset=UTF-8
DescriptionWidth=[n | *]
Le mot-clé DescriptionWidth vous permet de spécifier la taille en caractères de la colonne description.
Avec -DescriptionWidth (ou si l'option n'est pas définie), mod_autoindex calcule la meilleure taille.
DescriptionWidth=n fixe la taille de la colonne à n octets.
DescriptionWidth=* ajuste la taille de la colonne à la plus longue chaîne de description. Voir la section concernant AddDescription pour les dangers inhérants à la troncature des descriptions.
FancyIndexing
Cette option active l'indexation "améliorée" des répertoires, c'est à dire avec en-têtes de colonnes sous forme d'hyper-liens auto-référants.
FoldersFirst
Lorsque cette option est activée, la liste des sous-répertoires apparaîtra toujours en premier, suivie de la liste des fichiers normaux du répertoire. Le listing comporte principalement deux parties, les fichiers et les sous-répertoires, chacun d'eux étant trié séparément et les sous-répertoires affichés en premier. Par exemple, si l'ordre de tri est décroissant par nom, et si FoldersFirst est activé, le sous-répertoire Zed sera affiché avant le sous-répertoire Beta, qui sera lui-même affiché avant les fichiers normaux Gamma et Alpha. Cette option n'a d'effet que si FancyIndexing est aussi activé.
HTMLTable
Cette option pour l'affichage FancyIndexing permet de construire une table simple pour l'affichage de l'index du répertoire. Cette option s'avèrera particulièrement nécessaire pour les plates-formes où utf-8 est activé et dans le cas où les noms de fichiers ou les chaînes de description alternent entre les ordres de lecture gauche à droite et droite à gauche.
IconsAreLinks
Configure la partie réservée aux icônes de l'ancrage pour le nom de fichier, dans le cas d'un affichage "amélioré".
IconHeight[=pixels]
Si cette option est présente, en combinaison avec IconWidth, le serveur va inclure les attributs height et width dans la balise img qui référence le fichier de l'icône. Ceci va permettre au navigateur de prévoir les caractéristiques de la page sans devoir attendre que toutes les images aient été chargées. En l'absence de cette option, c'est la hauteur standard définie par le logiciel Apache httpd qui est choisie comme valeur par défaut. Cette option n'a d'effet que si FancyIndexing est aussi activé.
IconWidth[=pixels]
Si cette option est présente, en combinaison avec IconHeight, le serveur va inclure les attributs height et width dans la balise img qui référence le fichier de l'icône. Ceci va permettre au navigateur de prévoir les caractéristiques de la page sans devoir attendre que toutes les images aient été chargées. En l'absence de cette option, c'est la largeur standard définie par le logiciel Apache httpd qui est choisie comme valeur par défaut.
IgnoreCase
Si cette option est activée, les noms sont triés sans tenir compte de la casse. Par exemple, si le tri s'effectue sur les noms dans l'ordre croissant, et si IgnoreCase est activé, le fichier Zeta apparaîtra après le fichier alfa (Note : le fichier GAMMA apparaîtra toujours avant le fichier gamma).
IgnoreClient
Si cette option est activée, mod_autoindex va ignorer toutes les variables de requête fournies par le client, y compris les informations de tri (ce qui implique l'activation de l'option SuppressColumnSorting).
NameWidth=[n | *]
Le mot-clé NameWidth vous permet de spécifier la largeur en octets de la colonne correspondant au nom du fichier.
Avec -NameWidth (ou si l'option n'est pas définie), mod_autoindex va calculer la meilleure largeur possible, mais jusqu'à une largeur maximale de 20 octets.
NameWidth=n fixe la largeur de la colonne à n octets.
NameWidth=* définit la largeur de colonne à la valeur nécessaire.
ScanHTMLTitles
L'activation de cette option permet d'extraire le titre des documents HTML dans le cas d'un affichage "amélioré". Si le fichier ne possède aucune description définie par la directive AddDescription, httpd va lire le document pour tenter d'en extraire le titre. Ce processus est coûteux en ressources disque et CPU.
ShowForbidden
Si cette option est activée, Apache httpd affichera les fichiers normalement cachés suite au retour des valeurs HTTP_UNAUTHORIZED ou HTTP_FORBIDDEN par la sous-requête.
SuppressColumnSorting
Si cette option est activée, Apache httpd supprimera les liens hyper-texte dans les en-têtes de colonnes dans le cas d'un affichage "amélioré". Par défaut, ces en-têtes constituent des liens hyper-texte, et la sélection de l'un d'entre eux va trier l'index du répertoire en fonction des valeurs de la colonne correspondante. Cependant, les arguments de la chaîne de paramètres de la requête ajoutés à l'URL seront toujours ignorés. Ce comportement est contrôlé par l'option IndexOptions IgnoreClient.
SuppressDescription
L'activation de cette option va supprimer la description des fichiers dans le cas d'un affichage "amélioré". Par défaut aucune description de fichier n'est définie, et par conséquent l'utilisation de cette option va permettre de récupérer un espace à l'écran de 23 caractères pouvant être utilisé pour autre chose. Voir la directive AddDescription pour plus d'informations à propos de la définition des descriptions de fichiers. Voir aussi l'option d'index DescriptionWidth pour limiter la taille de la colonne description. Cette option n'a d'effet que si FancyIndexing est aussi activé.
SuppressHTMLPreamble
Si le répertoire contient effectivement le fichier spécifié par la directive HeaderName, le module inclut en général le contenu du fichier après avoir inséré un préambule HTML standard (<html>, <head>, etc...). L'activation de l'option SuppressHTMLPreamble supprime l'insertion de ce préambule, et le module va alors commencer l'affichage directement par le contenu du fichier d'en-tête. Dans ce cas par contre, le fichier d'en-tête doit contenir des instructions HTML appropriées. S'il n'y a pas de fichier d'en-tête, le préambule est généré comme dans le cas général. Si vous spécifiez aussi une directive ReadmeName, et si ce fichier existe, les balises de fermeture closing </body></html> seront aussi omises dans la sortie, en supposant que vous ayez placé ces balises de fermeture dans ce fichier.
SuppressIcon
L'activation de cette option supprime l'affichage des icônes dans le cas d'un affichage "amélioré". La combinaison de SuppressIcon et SuppressRules permet de générer une sortie au format HTML 3.2 qui, selon les dernières spécifications, interdit les éléments img et hr dans les blocs pre (utilisés pour formater les affichages "améliorés").
SuppressLastModified
L'activation de cette option supprime l'affichage de la date de dernière modification dans le cas d'un affichage "amélioré". Cette option n'a d'effet que si FancyIndexing est aussi activé.
SuppressRules
L'activation de cette option supprime l'affichage des lignes horizontales (éléments hr) dans les index de répertoires. La combinaison de SuppressIcon et SuppressRules permet de générer une sortie au format HTML 3.2 qui, selon les dernières spécifications, interdit les éléments img et hr dans les blocs pre (utilisés pour formater les affichages "améliorés"). Cette option n'a d'effet que si FancyIndexing est aussi activé.
SuppressSize
L'activation de cette option supprime l'affichage de la taille du fichier dans le cas d'un affichage "amélioré". Cette option n'a d'effet que si FancyIndexing est aussi activé.
TrackModified
Cette option renvoie les valeurs Last-Modified et ETag pour le répertoire indexé dans l'en-tête HTTP. Elle n'est valide que si le système d'exploitation et le système de fichiers renvoient des résultats appropriés pour la fonction stat(). C'est le cas de certains systèmes Unix, ainsi que JFS sous OS/2 ou les volumes NTFS sous Win32. Ce n'est par contre pas le cas des volumes FAT Win32 et OS/2. Lorsque cette option est activée, le client ou le mandataire peuvent détecter les changements dans la liste des fichiers lorsqu'ils effectuent une requête HEAD. Notez que certains systèmes d'exploitation détectent correctement les nouveaux fichiers et les fichiers supprimés, mais ne détectent pas les modifications de tailles ou de dates des fichiers du répertoire. Les modifications de taille ou de date d'un fichier existant ne mettent pas à jour l'en-tête Last-Modified sur toutes les plate-formes Unix. Si c'est le cas, laissez cette option désactivée.
Type=type MIME (Versions 2.0.61 et supérieures du serveur HTTP Apache)
Le mot-clé Type vous permet de spécifier le type MIME de la page générée. La valeur par défaut est text/html.
IndexOptions Type=text/plain
UseOldDateFormat (Apache HTTP Server versions 2.4.26 et ultérieures)
Le format de date utilisé dans le champ Last Modified avait été modifié par inadvertance de "%d-%b-%Y %H:%M" en "%Y-%m-%d %H:%M" dans la version 2.4.0. Cette option permet de restaurer le format de date des versions 2.2 et antérieures.
VersionSort (Versions 2.0a3 et supérieures du serveur HTTP Apache)
Le mot-clé VersionSort permet de trier les fichiers contenant des numéros de version d'une manière spécifique. Les chaînes sont triées comme d'habitude, excepté les sous-chaînes de chiffres du nom de fichier et de sa description qui sont comparées en fonction de leur valeur numérique.

Exemple :

foo-1.7
foo-1.7.2
foo-1.7.12
foo-1.8.2
foo-1.8.2a
foo-1.12

Si le nombre commence par le chiffre 0, il est considéré comme la partie fractionnaire d'un nombre :

foo-1.001
foo-1.002
foo-1.030
foo-1.04

XHTML (Versions 2.0.49 et supérieures du serveur HTTP Apache)
Le mot-clé XHTML enjoint mod_autoindex de générer du code XHTML 1.0 au lieu de HTML 3.2. Cette option n'a d'effet que si FancyIndexing est aussi activé.
Options d'index incrémentales

Vous devez porter une attention particulière à la manière dont les IndexOptions multiples sont traitées.

  • Plusieurs directives IndexOptions apparaissant dans la même section directory sont maintenant fusionnées. Le résultat de :
    <Directory "/foo">
    IndexOptions HTMLTable
    IndexOptions SuppressColumnsorting
</Directory>

    est équivalent à

    IndexOptions HTMLTable SuppressColumnsorting
  • L'ajout de la syntaxe incrémentale (en préfixant les mots-clés avec + ou -).

Chaque fois qu'un mot-clé préfixé par '+' ou '-' est trouvé, il est appliqué aux définitions des IndexOptions courantes (qui ont été éventuellement héritées d'un directory de niveau supérieur). Par contre, si un mot-clé non préfixé est trouvé, il supprime toutes les definitions héritées, ainsi que toute définition incrémentale. Considérons l'exemple suivant :

IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
IndexOptions +SuppressSize

L'effet global est équivalent à l'effet qu'aurait provoqué IndexOptions FancyIndexing +SuppressSize, car l'option non préfixée FancyIndexing annule les mots-clés incrémentaux situés avant elle, mais leur permet ensuite de s'incrémenter à nouveau.

Pour définir inconditionnellement les IndexOptions pour un répertoire particulier, tout en supprimant les définitions héritées, spécifiez les mots-clés sans préfixe + ou -

Directive IndexOrderDefault

Description: | Définit l'ordre d'affichage par défaut d'un index de répertoire
Syntaxe: | IndexOrderDefault Ascending|Descending Name|Date|Size|Description
Défaut: | IndexOrderDefault Ascending Name
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive IndexOrderDefault s'utilise en combinaison avec l'option d'index FancyIndexing. Par défaut, les index de répertoires "améliorés" sont affichés selon l'ordre croissant des noms de fichiers ; la directive IndexOrderDefault vous permet de modifier ce comportement.

La directive IndexOrderDefault accepte deux arguments. Le premier est soit Ascending, soit Descending, et indique l'ordre de tri. Le second doit prendre une des valeurs Name, Date, Size, ou Description, et permet d'identifier la clé primaire. La clé secondaire est toujours le nom du fichier selon un ordre croissant.

Si vous le désirez, vous pouvez empêcher le client de modifier l'ordre de tri de la liste en ajoutant l'option d'index SuppressColumnSorting qui supprime le lien de définition du tri de l'en-tête de la colonne, ainsi que l'option IgnoreClient qui empêche ce même client de passer outre vos préférences de tri en ajoutant manuellement des options de tri à la chaîne de paramètres de la requête.

Directive IndexStyleSheet

Description: | Ajoute une feuille de style CSS à l'index du répertoire
Syntaxe: | IndexStyleSheet chemin-url
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive IndexStyleSheet permet de définir le nom du fichier qui servira de feuille de style CSS pour l'index.

IndexStyleSheet "/css/style.css"

L'utilisation de cette directive en conjonction avec IndexOptions HTMLTable ajoute plusieurs classes CSS au document HTML résultant. Un identifiant CSS indexlist est attribué à l'ensemble de la table et les classes suivantes sont associées aux différentes parties du listing :

Classe | Définition
tr.indexhead | Ligne d'en-tête du listing
th.indexcolicon and td.indexcolicon | Colonne de l'icône
th.indexcolname and td.indexcolname | Colonne du nom du fichier
th.indexcollastmod and td.indexcollastmod | Colonne de la date de dernière modification
th.indexcolsize and td.indexcolsize | Colonne de la taille du fichier
th.indexcoldesc and td.indexcoldesc | Colonne de la description
tr.breakrow | Pied de page
tr.odd and tr.even | Alternance des lignes paires et impaires

Directive ReadmeName

Description: | Nom du fichier dont le contenu sera inséré à la fin de l'index
Syntaxe: | ReadmeName nom-fichier
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_autoindex

La directive ReadmeName permet de définir le nom du fichier dont le contenu sera ajouté à la fin de l'index. nom-fichier est le nom du fichier à inclure, et est considéré comme relatif au répertoire faisant l'objet de l'index. Si nom-fichier commence par un slash '/', comme dans l'exemple 2, il sera considéré comme relatif au répertoire défini par la directive DocumentRoot.

# Example 1
ReadmeName FOOTER.html
# Example 2
ReadmeName /include/FOOTER.html

Voir aussi la directive HeaderName, où cette fonctionnalité est décrite plus en détails.


mod_brotli - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_brotli

Description: | Compress content via Brotli before it is delivered to the client
Status: | Extension
Module Identifier: | brotli_module
Source File: | mod_brotli.c
Compatibility: | Available in version 2.4.26 and later.

Summary

The mod_brotli module provides the BROTLI_COMPRESS output filter that allows output from your server to be compressed using the brotli compression format before being sent to the client over the network. This module uses the Brotli library found at https://github.com/google/brotli.

Bugfix checklist

  • httpd changelog
  • Known issues
  • Report a bug

See also

  • Filters

Sample Configurations

Compression and TLS

Some web applications are vulnerable to an information disclosure attack when a TLS connection carries compressed data. For more information, review the details of the "BREACH" family of attacks.

This is a simple configuration that compresses common text-based content types.

Compress only a few types

AddOutputFilterByType BROTLI_COMPRESS text/html text/plain text/xml text/css text/javascript application/javascript

Enabling Compression

Compression and TLS

Some web applications are vulnerable to an information disclosure attack when a TLS connection carries compressed data. For more information, review the details of the "BREACH" family of attacks.

Output Compression

Compression is implemented by the BROTLI_COMPRESS filter. The following directive will enable compression for documents in the container where it is placed:

SetOutputFilter BROTLI_COMPRESS
SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-brotli

If you want to restrict the compression to particular MIME types in general, you may use the AddOutputFilterByType directive. Here is an example of enabling compression only for the html files of the Apache documentation:

<Directory "/your-server-root/manual">
    AddOutputFilterByType BROTLI_COMPRESS text/html
</Directory>

Note

The BROTLI_COMPRESS filter is always inserted after RESOURCE filters like PHP or SSI. It never touches internal subrequests.

Note

There is an environment variable no-brotli, set via SetEnv, which will disable brotli compression for a particular request, even if it is supported by the client.

Dealing with proxy servers

The mod_brotli module sends a Vary: Accept-Encoding HTTP response header to alert proxies that a cached response should be sent only to clients that send the appropriate Accept-Encoding request header. This prevents compressed content from being sent to a client that will not understand it.

If you use some special exclusions dependent on, for example, the User-Agent header, you must manually configure an addition to the Vary header to alert proxies of the additional restrictions. For example, in a typical configuration where the addition of the BROTLI_COMPRESS filter depends on the User-Agent, you should add:

Header append Vary User-Agent

If your decision about compression depends on other information than request headers (e.g. HTTP version), you have to set the Vary header to the value *. This prevents compliant proxies from caching entirely.

Example

Header set Vary *

Serving pre-compressed content

Since mod_brotli re-compresses content each time a request is made, some performance benefit can be derived by pre-compressing the content and telling mod_brotli to serve them without re-compressing them. This may be accomplished using a configuration like the following:

<IfModule mod_headers.c>
    # Serve brotli compressed CSS files if they exist
    # and the client accepts brotli.
    RewriteCond "%{HTTP:Accept-encoding}" "br"
    RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
    RewriteRule "^(.*)\.css"              "$1\.css\.br" [QSA]

    # Serve brotli compressed JS files if they exist
    # and the client accepts brotli.
    RewriteCond "%{HTTP:Accept-encoding}" "br"
    RewriteCond "%{REQUEST_FILENAME}\.br" "-s"
    RewriteRule "^(.*)\.js"               "$1\.js\.br" [QSA]

    # Serve correct content types, and prevent double compression.
    RewriteRule "\.css\.br$" "-" [T=text/css,E=no-brotli:1]
    RewriteRule "\.js\.br$"  "-" [T=text/javascript,E=no-brotli:1]

    <FilesMatch "(\.js\.br|\.css\.br)$">
      # Serve correct encoding type.
      Header append Content-Encoding br

      # Force proxies to cache brotli &
      # non-brotli css/js files separately.
      Header append Vary Accept-Encoding
    </FilesMatch>
</IfModule>

BrotliAlterETag Directive

Description: | How the outgoing ETag header should be modified during compression
Syntax: | BrotliAlterETag AddSuffix|NoChange|Remove
Default: | BrotliAlterETag AddSuffix
Context: | server config, virtual host
Status: | Extension
Module: | mod_brotli

The BrotliAlterETag directive specifies how the ETag hader should be altered when a response is compressed.

AddSuffix

Append the compression method onto the end of the ETag, causing compressed and uncompressed representations to have unique ETags. In another dynamic compression module, mod_deflate, this has been the default since 2.4.0. This setting prevents serving "HTTP Not Modified" (304) responses to conditional requests for compressed content.

NoChange

Don't change the ETag on a compressed response. In another dynamic compression module, mod_deflate, this has been the default prior to 2.4.0. This setting does not satisfy the HTTP/1.1 property that all representations of the same resource have unique ETags.

Remove

Remove the ETag header from compressed responses. This prevents some conditional requests from being possible, but avoids the shortcomings of the preceding options.

BrotliCompressionMaxInputBlock Directive

Description: | Maximum input block size
Syntax: | BrotliCompressionMaxInputBlock value
Default: | (automatic)
Context: | server config, virtual host
Status: | Extension
Module: | mod_brotli

The BrotliCompressionMaxInputBlock directive specifies the maximum input block size between 16 and 24, with the caveat that larger block sizes require more memory.

BrotliCompressionQuality Directive

Description: | Compression quality
Syntax: | BrotliCompressionQuality value
Default: | BrotliCompressionQuality 5
Context: | server config, virtual host
Status: | Extension
Module: | mod_brotli

The BrotliCompressionQuality directive specifies the compression quality (a value between 0 and 11). Higher quality values result in better, but also slower compression.

BrotliCompressionWindow Directive

Description: | Brotli sliding compression window size
Syntax: | BrotliCompressionWindow value
Default: | BrotliCompressionWindow 18
Context: | server config, virtual host
Status: | Extension
Module: | mod_brotli

The BrotliCompressionWindow directive specifies the brotli sliding compression window size (a value between 10 and 24). Larger window sizes can improve compression quality, but require more memory.

BrotliFilterNote Directive

Description: | Places the compression ratio in a note for logging
Syntax: | BrotliFilterNote [type] notename
Context: | server config, virtual host
Status: | Extension
Module: | mod_brotli

The BrotliFilterNote directive specifies that a note about compression ratios should be attached to the request. The name of the note is the value specified for the directive. You can use that note for statistical purposes by adding the value to your access log.

Example

BrotliFilterNote ratio

LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' brotli
CustomLog "logs/brotli_log" brotli

If you want to extract more accurate values from your logs, you can use the type argument to specify the type of data left as a note for logging. type can be one of:

Input
Store the byte count of the filter's input stream in the note.
Output
Store the byte count of the filter's output stream in the note.
Ratio
Store the compression ratio (output/input * 100) in the note. This is the default, if the type argument is omitted.

Thus you may log it this way:

Accurate Logging

BrotliFilterNote Input instream
BrotliFilterNote Output outstream
BrotliFilterNote Ratio ratio

LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' brotli
CustomLog "logs/brotli_log" brotli

See also

  • mod_log_config

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_buffer - Serveur Apache HTTP Version 2.4

Module Apache mod_buffer

Description: | Support de la mise en tampon des requêtes
Statut: | Extension
Identificateur de Module: | buffer_module
Fichier Source: | mod_buffer.c
Compatibilité: | Disponible depuis les versions 2.3 et supérieures d'Apache

Sommaire

Ce module fournit la possibilité de mettre en tampon les piles des filtres en entrée et sortie.

Dans certaines situations, les générateurs de contenu créent des contenus composés de petits tronçons. Afin de permettre la réutilisation de la mémoire, les éléments de mémoire attribués aux tronçons ont toujours une taille de 8k, quelle que soit la taille du tronçon lui-même. Lorsqu'une requête génère de nombreux petits tronçons, une grande quantité de mémoire peut être mobilisée par le traitement de la requête, et une grande quantité de données transmises sans nécessité. Pour y remédier, l'utilisation d'un tampon rassemble la réponse en un nombre de tronçons le plus petit possible.

Lorsque httpd est utilisé comme frontal d'un générateur de contenu consommant beaucoup de ressources, la mise en tampon de la réponse peut permettre à ce dernier d'effectuer le traitement et de libérer les ressources plus ou moins rapidement, en fonction de la manière dont il a été conçu.

Le filtre de mise en tampon peut être ajouté aux piles des filtres en entrée ou en sortie, selon les besoins, à l'aide des directives SetInputFilter, SetOutputFilter, AddOutputFilter ou AddOutputFilterByType.

Utilisation d'un tampon avec mod_include

AddOutputFilterByType INCLUDES;BUFFER text/html
Les filtres de mise en tampon lisent la requête/réponse en RAM, puis la reconditionnent sous la forme d'un nombre d'éléments mémoire le plus petit possible, au prix d'une consommation de temps CPU. Lorsque la requête/réponse est déjà conditionnée de manière satisfaisante, sa mise en tampon pourrait s'avérer encore plus lente qu'en l'absence d'utilisation de tampon. C'est pourquoi ces filtres doivent être utilisés avec précautions, et seulement si nécessaire.

Traitement des bugs

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

Voir aussi

  • Les filtres

Directive BufferSize

Description: | Taille maximale en octets du filtre par tampon
Syntaxe: | BufferSize entier
Défaut: | BufferSize 131072
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_buffer

La directive BufferSize permet de spécifier la quantité de données en octets qui sera mise en tampon avant d'être lue depuis ou écrite vers chaque requête. La valeur par défaut est 128 ko.


mod_cache - Serveur Apache HTTP Version 2.4

Module Apache mod_cache

Description: | Filtre de mise en cache HTTP conforme à la RFC 2616
Statut: | Extension
Identificateur de Module: | cache_module
Fichier Source: | mod_cache.c

Sommaire

Ce module doit être utilisé avec précautions car lorsque la directive CacheQuickHandler est définie à sa valeur par défaut on, les directives Allow and Deny sont court-circuitées. Vous ne devez donc pas activer la gestion rapide de la mise en cache pour un contenu auquel vous souhaitez limiter l'accès en fonction du nom d'hôte du client, de l'adresse IP ou d'une variable d'environnement.

mod_cache implémente un filtre de mise en cache de contenu HTTP conforme à la RFC 2616, avec support de la mise en cache des réponses dont le contenu a été négocié et comportant l'en-tête Vary.

La mise en cache conforme à la RFC 2616 fournit un mécanisme permettant de vérifier si un contenu expiré ou dépassé est encore à jour, et peut apporter un gain de performances significatif si le serveur original supporte les requêtes conditionnelles en prenant en compte l'en-tête de requête HTTP If-None-Match. Le contenu n'est ainsi régénéré que lorsqu'il a été modifié, et non lorsqu'il a expiré.

En tant que filtre, mod_cache peut être placé en face d'un contenu issu de tout gestionnaire, y compris des fichiers à accès séquentiel (servis depuis un disque lent mis en cache sur un gros disque), la sortie d'un script CGI ou d'un générateur de contenu dynamique, ou du contenu mandaté depuis un autre serveur.

Dans la configuration par défaut, mod_cache place le filtre de mise en cache aussi loin que possible dans la pile de filtres, utilisant le gestionnaire rapide pour court-circuiter tout traitement par requête lors de l'envoi du contenu au client. Dans ce mode opératoire, mod_cache peut être considéré comme un serveur mandataire avec cache fixé en tête du serveur web, alors qu'il s'exécute dans ce même serveur web.

Lorsque le gestionnaire rapide est désactivé via la directive CacheQuickHandler, il devient possible d'insérer le filtre CACHE à un point de la pile de filtres choisi par l'administrateur. Ceci permet de mettre en cache un contenu avant que celui-ci ne soit personnalisé par le filtre mod_include, ou éventuellement compressé par le filtre mod_deflate.

Dans le mode de fonctionnement normal, mod_cache peut être contrôlé par les en-têtes Cache-Control et Pragma envoyés par un client dans une requête, ou par un serveur dans une réponse. Dans des circonstances exceptionnelles, mod_cache peut cependant être configuré pour outrepasser ces en-têtes et forcer un comportement spécifique au site, bien qu'un tel comportement sera limité à ce cache seulement, et n'affectera pas les opérations des autres caches qui peuvent s'insérer entre le client et le serveur, et ce type de configuration ne doit donc être utiliser qu'en cas de nécessité absolue.

La RFC 2616 permet au cache de renvoyer des données périmées pendant que l'entrée périmée correspondante est mise à jour depuis le serveur original, et mod_cache supporte cette fonctionnalité lorsque la directive CacheLock est configurée en conséquence. De telles réponses comportent un en-tête HTTP Warning contenant un code de réponse 110. La RFC 2616 permet aussi au cache de renvoyer des données périmées lorsque la tentative de mise à jour des données périmées renvoie une erreur 500 ou supérieure, et cette fonctionnalité est supportée par défaut par mod_cache. De telles réponses comportent un en-tête HTTP Warning contenant un code de réponse 111.

mod_cache requiert les services d'un ou plusieurs modules de gestion de stockage. La distribution Apache de base inclut les modules de gestion de stockage suivants :

mod_cache_disk
implémente un gestionnaire de stockage sur disque. Les en-têtes et corps sont stockés séparément sur le disque dans une structure de répertoires basée sur le condensé md5 de l'URL mise en cache. Plusieurs réponses à contenu négocié peuvent être stockées en même temps, mais la mise en cache de contenus partiels n'est pas supportée par ce module. L'utilitaire htcacheclean permet de lister et de supprimer les URLs mises en cache, et de maintenir le cache en deçà de certaines limites de taille et de nombre d'inodes.
mod_cache_socache
Implémente un gestionnaire de stockage basé sur un cache d'objets partagés. Les en-têtes et corps sont stockés ensemble sous une seule clé basée sur l'URL de la réponse mise en cache. Des réponses à contenus multiples négociés peuvent être stockées simultanément, mais ce module ne supporte pas la mise en cache de contenus partiels.

Pour de plus amples détails, une description, et des exemples, reportez-vous au Guide de la mise en cache.

Traitement des bugs

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

Voir aussi

  • Guide de la mise en cache

Modules apparentés et directives

Modules Apparentés Directives Apparentées
  • mod_cache_socache
  • CacheRoot
  • CacheDirLevels
  • CacheDirLength
  • CacheMinFileSize
  • CacheMaxFileSize
  • CacheSocache
  • CacheSocacheMaxTime
  • CacheSocacheMinTime
  • CacheSocacheMaxSize
  • CacheSocacheReadSize
  • CacheSocacheReadTime

Exemple de configuration

Extrait de httpd.conf

#
# Exemple de configuration du cache
#
LoadModule cache_module modules/mod_cache.so
<IfModule mod_cache.c>
    LoadModule cache_disk_module modules/mod_cache_disk.so
    <IfModule mod_cache_disk.c>
        CacheRoot "c:/cacheroot"
        CacheEnable disk  "/"
        CacheDirLevels 5
        CacheDirLength 3
    </IfModule>

    # Lorsqu'on sert de mandataire, on ne met pas en cache la liste
# des mises à jour de sécurité
    CacheDisable "http://security.update.server/update-list/"
</IfModule>

Eviter une tempête de requête

Lorsqu'une entrée du cache est périmée, mod_cache soumet une requête conditionnelle au processus d'arrière-plan, qui est censé confirmer la validité de l'entrée du cache, ou dans la négative envoyer une entrée mise à jour.

Un court mais non négligeable laps de temps existe entre le moment où l'entrée du cache est périmée, et le moment où elle est mise à jour. Sur un serveur fortement chargé, un certain nombre de requêtes peut arriver pendant ce laps de temps, et provoquer une tempête de requêtes susceptibles de saturer le processus d'arrière-plan de manière soudaine et imprédictible.

Pour contenir cette tempête, on peut utiliser la directive CacheLock afin de définir un répertoire où seront créés à la volée des verrous pour les URLs. Ces verrous sont utilisés comme autant d'indications par les autres requêtes, soit pour empêcher une tentative de mise en cache (un autre processus est en train de récupérer l'entité), soit pour indiquer qu'une entrée périmée est en cours de mise à jour (pendant ce temps, c'est le contenu périmé qui sera renvoyé).

Mise en cache initiale d'une entrée

Lorsqu'une entité est mise en cache pour la première fois, un verrou est créé pour cette entité jusqu'à ce que la réponse ait été entièrement mise en cache. Pendant la durée de vie du verrou, le cache va empêcher une seconde tentative de mise en cache de la même entité. Bien que cela ne suffise pas à contenir la tempête de requêtes, toute tentative de mettre en cache la même entité plusieurs fois simultanément est stoppée.

Mise à jour d'une entrée périmée

Lorsqu'une entrée atteint la limite de sa durée de vie, et devient par conséquent périmée, un verrou est créé pour cette entité jusqu'à ce que la réponse ait été soit confirmée comme encore valide, soit remplacée par le processus d'arrière-plan. Pendant la durée de vie du verrou, une seconde requête entrante va provoquer le renvoi de la donnée périmée, et la tempête de requêtes sera contenue.

Verrous et en-tête Cache-Control: no-cache

Les verrous ne sont utilisés qu'à titre indicatif pour enjoindre le cache à être plus coopératif avec les serveurs d'arrière-plan, et il est possible de passer outre si nécessaire. Si le client envoie une requête contenant un en-tête Cache-Control imposant un nouveau téléchargement de l'entité, tout verrou éventuel sera ignoré, la requête du client sera honorée immédiatement, et l'entrée du cache mise à jour.

Comme mécanisme de sécurité supplémentaire, la durée de vie maximale des verrous est configurable. Lorsque cette limite est atteinte, le verrou est supprimé et une autre requête peut alors en créer un nouveau. Cette durée de vie peut être définie via la directive CacheLockMaxAge, et sa valeur par défaut est de 5 secondes.

Exemple de configuration

Activation du verrouillage du cache

#
# Active le verrouillage du cache
#
<IfModule mod_cache.c>
    CacheLock on
    CacheLockPath "/tmp/mod_cache-lock"
    CacheLockMaxAge 5
</IfModule>

Contrôle fin via le filtre CACHE

Dans son mode de fonctionnement par défaut, le cache s'exécute sous la forme d'un gestionnaire rapide, court-circuitant la majorité des traitements du serveur et fournissant ainsi une mise en cache possédant les plus hautes performances disponibles.

Dans ce mode, le cache s'incruste devant le serveur, comme si un mandataire de mise en cache indépendant RFC 2616 était placé devant ce dernier.

Bien que que ce mode offre les meilleures performances, les administrateurs peuvent souhaiter, dans certaines circonstances, effectuer des traitements sur la requête après que cette dernière ait été mise en cache, comme ajouter du contenu personnalisé à la page mise en cache, ou appliquer des restrictions d'autorisations au contenu. Pour y parvenir, l'administrateur sera alors souvent forcé de placer des serveurs mandataires inverses indépendants soit derrière, soit devant le serveur de mise en cache.

Pour résoudre ce problème, la directive CacheQuickHandler peut être définie à off, afin que le serveur traite toutes les phases normalement exécutées par une requête non mise en cache, y compris les phases d'authentification et d'autorisation.

En outre, l'administrateur peut éventuellement spécifier le point précis dans la chaîne de filtrage où devra intervenir la mise en cache en ajoutant le filtre CACHE à la chaîne de filtrage en sortie.

Par exemple, pour mettre en cache le contenu avant d'appliquer une compression à la réponse, placez le filtre CACHE avant le filtre DEFLATE comme dans l'exemple suivant :

# Mise en cache du contenu avant la compression optionnelle
CacheQuickHandler off
AddOutputFilterByType CACHE;DEFLATE text/plain

Une autre possibilité consiste à mettre en cache le contenu avant l'ajout de contenu personnalisé via mod_include (ou tout autre filtre de traitement de contenu). Dans l'exemple suivant, les modèles contenant des balises comprises par mod_include sont mis en cache avant d'être interprétés :

# Mise en cache du contenu avant l'intervention de mod_include et
   # mod_deflate
CacheQuickHandler off
AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html

Vous pouvez insérer le filtre CACHE en tout point de la chaîne de filtrage. Dans l'exemple suivant, le contenu est mis en cache après avoir été interprété par mod_include, mais avant d'être traité par mod_deflate :

# Mise en cache du contenu entre les interventions de mod_include et
   # mod_deflate
CacheQuickHandler off
AddOutputFilterByType INCLUDES;CACHE;DEFLATE text/html

Avertissement :

Si pour une raison ou pour une autre, le point d'insertion du filtre CACHE dans la chaîne de filtrage est modifié, vous devez vider votre cache pour être sûr que les données servies soient à jour. En effet, mod_cache n'est pas en mesure d'effectuer cette opération à votre place.

Etat du cache et journalisation

Lorsque mod_cache a décidé s'il devait ou non servir une entité depuis le cache, les raisons précises de cette décision sont enregistrées dans l'environnement du sous-processus interne à la requête sous la clé cache-status. Cette information peut être journalisée via la directive LogFormat comme suit :

LogFormat "%{cache-status}e ..."

En fonction de la décision prise, l'information est aussi écrite dans l'environnement du sous-processus sous une des quatre clés suivantes :

cache-hit
Le contenu a été servi depuis le cache.
cache-revalidate
Le contenu du cache était périmé, a été mis à jour avec succès, puis servi depuis le cache.
cache-miss
Le contenu n'était pas dans le cache et a été servi directement depuis le serveur demandé.
cache-invalidate
L'entité du cache est devenue invalide suite à une requête d'un type autre que GET ou HEAD.

Il est alors possible d'envisager une journalisation conditionnelle du traitement des requêtes par rapport au cache comme dans l'exemple suivant :

CustomLog "cached-requests.log" common env=cache-hit
CustomLog "uncached-requests.log" common env=cache-miss
CustomLog "revalidated-requests.log" common env=cache-revalidate
CustomLog "invalidated-requests.log" common env=cache-invalidate

Pour les concepteurs de modules, une accroche (hook) nommée cache_status est disponible et permet aux modules de répondre aux résultats de la vérification du cache ci-dessus de manière personnalisée.

Directive CacheDefaultExpire

Description: | La durée par défaut de mise en cache d'un document lorsqu'aucune date d'expiration n'a été spécifiée.
Syntaxe: | CacheDefaultExpire secondes
Défaut: | CacheDefaultExpire 3600 (une heure)
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

La directive CacheDefaultExpire permet de spécifier un temps par défaut, en secondes, pendant lequel sera conservé dans le cache un document qui ne possède ni date d'expiration, ni date de dernière modification. La valeur de cette directive est écrasée par la valeur de la directive CacheMaxExpire si cette dernière est utilisée.

CacheDefaultExpire 86400

Directive CacheDetailHeader

Description: | Ajoute un en-tête X-Cache-Detail à la réponse.
Syntaxe: | CacheDetailHeader on|off
Défaut: | CacheDetailHeader off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache
Compatibilité: | Disponible depuis la version 2.3.9 d'Apache

Lorsque la directive CacheDetailHeader est définie à on, un en-tête X-Cache-Detail est ajouté à la réponse et contient les raisons précises d'une décision d'utilisation du cache vis à vis de cette dernière.

Ceci peut s'avérer utile au cours du développement de services RESTful mis en cache pour obtenir des informations supplémentaires à propos des décisions vis à vis du cache écrites dans les en-têtes de la réponse. Il est ainsi possible de vérifier si Cache-Control et d'autres en-têtes ont été correctement utilisés par le service et le client.

Si le gestionnaire normal est utilisé, cette directive peut se situer dans une section <Directory> ou <Location>. Si c'est le gestionnaire rapide qui est utilisé, elle doit se situer dans un contexte de serveur principal ou de serveur virtuel, sinon elle sera ignorée.

# Active l'en-tête X-Cache-Detail
CacheDetailHeader on

X-Cache-Detail: "conditional cache hit: entity refreshed" from localhost

Directive CacheDisable

Description: | Désactive la mise en cache des URLs spécifiées
Syntaxe: | CacheDisable chaîne-url | on
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

La directive CacheDisable enjoint mod_cache de ne pas mettre en cache l'URL spécifiée par chaîne URL, ainsi que les URLs de niveaux inférieurs.

Exemple

CacheDisable "/fichiers_locaux"

Si la directive se trouve à l'intérieur d'une section <Location>, le chemin doit être spécifié en dessous de la Location, et si le mot "on" est utilisé, la mise en cache sera désactivée pour l'ensemble de l'arborescence concernée par la section Location.

Exemple

<Location "/foo">
    CacheDisable on
</Location>

Avec les versions 2.2.12 et ultérieures, on peut définir la variable d'environnement no-cache pour une définition plus fine des ressources à mettre en cache.

Voir aussi

  • Les variables d'environnement dans Apache

Directive CacheEnable

Description: | Active la mise en cache des URLs spécifiées en utilisant le gestionnaire de stockage précisé
Syntaxe: | CacheEnable type de cache [chaîne URL]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_cache
Compatibilité: | Une chaîne URL telle que '/' s'appliquait à tout contenu en mandat direct dans les versions 2.2 et antérieures.

La directive CacheEnable enjoint mod_cache de mettre en cache l'URL précisée par chaîne URL, ainsi que les URLs de niveaux inférieurs. Le gestionnaire de stockage du cache est spécifié à l'aide de l'argument type de cache. La directive CacheEnable peut être placée à l'intérieur d'une section <Location> ou <LocationMatch> pour indiquer que le contenu considéré peut être mis en cache. Si type de cache a pour valeur disk, mod_cache utilisera le gestionnaire de stockage sur disque implémenté par mod_cache_disk. Pour que mod_cache utilise le gestionnaire de stockage basé sur le cache d'objets partagés implémenté par mod_cache_socache, spécifiez socache comme valeur du paramètre type de cache.

Si les différentes directives CacheEnable spécifient des URLs qui se recoupent (comme dans l'exemple ci-dessous), tous les gestionnaires de stockage possibles seront lancés, jusqu'au premier d'entre eux qui traitera effectivement la requête. L'ordre dans lequel les gestionnaires de stockage sont lancés est déterminé par l'ordre dans lequel apparaissent les directives CacheEnable dans le fichier de configuration. Les directives CacheEnable situées à l'intérieur de sections <Location> ou <LocationMatch> sont traitées avant les directives CacheEnable définies au niveau global.

En fonctionnement du type serveur mandataire direct, chaîne URL doit au moins débuter par un protocole pour lequel la mise en cache doit être activée.

# Mise en cache de contenu (gestionnaire normal seulement)
CacheQuickHandler off
<Location "/foo">
    CacheEnable disk
</Location>

# Mise en cache via une expression rationnelle (gestionnaire normal seulement)
CacheQuickHandler off
<LocationMatch "foo$">
    CacheEnable disk
</LocationMatch>

# Mise en cache de tous les contenus, à l'exception des URLs
# mandatées en direct (gestionnaire normal ou rapide)
CacheEnable  disk  /

# Mise en cache des URLs FTP mandatées (gestionnaire normal ou rapide)
CacheEnable  disk  ftp://

# Mise en cache des contenus mandatés en direct depuis www.example.org (gestionnaire normal ou rapide)
CacheEnable  disk  http://www.example.org/

Un nom d'hôte commençant par un caractère "*" correspondra à tout nom d'hôte se terminant par le suffixe considéré. Un nom d'hôte commençant par un caractère "." correspondra à tout nom d'hôte contenant le composant de nom de domaine qui suit ce caractère.

# Correspond à www.example.org et fooexample.org
CacheEnable  disk  "http://*example.org/"
# Correspond à www.example.org, mais pas à fooexample.org
CacheEnable  disk  "http://.example.org/"

Depuis la version 2.2.12, on peut définir la variable d'environnement no-cache pour une définition plus fine des ressources à mettre en cache.

Voir aussi

  • Les variables d'environnement dans Apache

Directive CacheHeader

Description: | Ajoute un en-tête X-Cache à la réponse.
Syntaxe: | CacheHeader on|off
Défaut: | CacheHeader off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache
Compatibilité: | Disponible depuis la version 2.3.9 d'Apache

Lorsque la directive CacheHeader est définie à on, un en-tête X-Cache est ajouté à la réponse et contient l'état du cache pour cette dernière. Si le gestionnaire normal est utilisé, cette directive peut se situer dans une section <Directory> ou <Location>. Si c'est le gestionnaire rapide qui est utilisé, elle doit se situer dans un contexte de serveur principal ou de serveur virtuel, sinon elle sera ignorée.

HIT
Le contenu était à jour et a été servi depuis le cache.
REVALIDATE
Le contenu était périmé, a été mis à jour, puis a été servi depuis le cache.
MISS
Le contenu n'a pas été servi depuis le cache, mais directement depuis le serveur demandé.
# Active l'en-tête X-Cache
CacheHeader on
X-Cache: HIT from localhost

Directive CacheIgnoreCacheControl

Description: | Ignore les en-têtes de requête enjoignant de ne pas servir le contenu au client depuis le cache
Syntaxe: | CacheIgnoreCacheControl On|Off
Défaut: | CacheIgnoreCacheControl Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache

Normalement, les requêtes contenant des en-têtes tels que Cache-Control: no-cache ou Pragma: no-cache ne sont pas servies depuis le cache. La directive CacheIgnoreCacheControl permet de modifier ce comportement. Avec CacheIgnoreCacheControl On, le serveur tentera de servir la ressource depuis le cache, même si la requête contient un des en-têtes cités plus haut. Les ressources qui requièrent une autorisation ne seront jamais mises en cache.

CacheIgnoreCacheControl On

Avertissement :

Cette directive permet de servir des ressources depuis le cache, même si le client a demandé à ce qu'il n'en soit pas ainsi. Le contenu servi est ainsi susceptible d'être périmé.

Voir aussi

  • CacheStorePrivate
  • CacheStoreNoStore

Directive CacheIgnoreHeaders

Description: | Ne pas stocker le(s) en-tête(s) spécifié(s) dans le cache.
Syntaxe: | CacheIgnoreHeaders en-tête [en-tête] ...
Défaut: | CacheIgnoreHeaders None
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache

En accord avec la RFC 2616, les en-têtes HTTP hop-by-hop ne sont pas stockés dans le cache. Les en-têtes HTTP suivant sont des en-têtes hop-by-hop, et en tant que tels, ne sont en aucun cas stockés dans le cache, quelle que soit la définition de la directive CacheIgnoreHeaders :

  • Connection
  • Keep-Alive
  • Proxy-Authenticate
  • Proxy-Authorization
  • TE
  • Trailers
  • Transfer-Encoding
  • Upgrade

La directive CacheIgnoreHeaders permet de spécifier quels en-têtes HTTP ne doivent pas être stockés dans le cache. Par exemple, il peut s'avérer pertinent dans certains cas de ne pas stocker les cookies dans le cache.

La directive CacheIgnoreHeaders accepte une liste d'en-têtes HTTP séparés par des espaces, qui ne doivent pas être stockés dans le cache. Si les en-têtes hop-by-hop sont les seuls à ne pas devoir être stockés dans le cache (le comportement compatible RFC 2616), la directive CacheIgnoreHeaders peut être définie à None.

Exemple 1

CacheIgnoreHeaders Set-Cookie

Exemple 2

CacheIgnoreHeaders None

Avertissement :

Si des en-têtes nécessaires à la bonne gestion du cache, comme Expires, ne sont pas stockés suite à la définition d'une directive CacheIgnoreHeaders, le comportement de mod_cache sera imprévisible.

Directive CacheIgnoreNoLastMod

Description: | Ignore le fait qu'une réponse ne possède pas d'en-tête Last Modified.
Syntaxe: | CacheIgnoreNoLastMod On|Off
Défaut: | CacheIgnoreNoLastMod Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

Normalement, les documents qui ne possèdent pas de date de dernière modification ne sont pas mis en cache. Dans certaines circonstances, la date de dernière modification est supprimée (au cours des traitements liés à mod_include par exemple), ou n'existe tout simplement pas. La directive CacheIgnoreNoLastMod permet de spécifier si les documents ne possèdant pas de date de dernière modification doivent être mis en cache, même sans date de dernière modification. Si le document ne possède ni date d'expiration, ni date de dernière modification, la valeur spécifiée par la directive CacheDefaultExpire servira à générer une date d'expiration.

CacheIgnoreNoLastMod On

Directive CacheIgnoreQueryString

Description: | Ignore la chaîne de paramètres lors de la mise en cache
Syntaxe: | CacheIgnoreQueryString On|Off
Défaut: | CacheIgnoreQueryString Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache

Normalement, les requêtes comportant une chaîne de paramètres sont mises en cache séparément si leurs chaînes de paramètres diffèrent. En accord avec la RFC 2616/13.9, cette mise en cache n'est effectuée séparément que si une date d'expiration est spécifiée. La directive CacheIgnoreQueryString permet la mise en cache de requêtes même si aucune date d'expiration est spécifiée, et de renvoyer une réponse depuis la cache même si les chaînes de paramètres diffèrent. Du point de vue du cache, la requête est traitée comme si elle ne possèdait pas de chaîne de paramètres lorsque cette directive est activée.

CacheIgnoreQueryString On

Directive CacheIgnoreURLSessionIdentifiers

Description: | Ignore les identifiants de session définis encodés dans l'URL lors de la mise en cache
Syntaxe: | CacheIgnoreURLSessionIdentifiers identifiant [identifiant] ...
Défaut: | CacheIgnoreURLSessionIdentifiers None
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache

Certaines applications encodent l'identifiant de session dans l'URL comme dans l'exemple suivant :

  • /une-application/image.gif;jsessionid=123456789
  • /une-application/image.gif?PHPSESSIONID=12345678

Ceci implique la mise en cache des ressources séparément pour chaque session, ce qui n'est en général pas souhaité. La directive CacheIgnoreURLSessionIdentifiers permet de définir une liste d'identifiants qui seront supprimés de la clé utilisée pour identifier une entité dans le cache, de façon à ce que les ressources ne soient pas stockées séparément pour chaque session.

CacheIgnoreURLSessionIdentifiers None vide la liste des identifiants ignorés. Autrement, chaque identifiant spécifié est ajouté à la liste.

Exemple 1

CacheIgnoreURLSessionIdentifiers jsessionid

Exemple 2

CacheIgnoreURLSessionIdentifiers None

Directive CacheKeyBaseURL

Description: | Remplace l'URL de base des clés du cache mandatées en inverse
Syntaxe: | CacheKeyBaseURL URL
Défaut: | CacheKeyBaseURL http://example.com
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache
Compatibilité: | Disponible depuis la version 2.3.9 d'Apache

Lorsque la directive CacheKeyBaseURL est utilisée, l'URL spécifiée sera utilisée comme URL de base pour calculer l'URL des clés du cache dans la configuration du mandataire inverse. Par défaut, c'est le protocole/nom d'hôte/port du serveur virtuel courant qui sera utilisé pour construire la clé de cache. Dans le cas d'un cluster de machines, si toutes les entrées du cache doivent posséder la même clé, cette directive permet de spécifier une nouvelle URL de base.

# Remplace l'URL de base de la clé de cache.
CacheKeyBaseURL "http://www.example.com/"
Prenez garde en définissant cette directive. Si deux serveurs virtuels distincts possèdent accidentellement la même URL de base, les entrées en provenance d'un serveur virtuel seront servies par l'autre.

Directive CacheLastModifiedFactor

Description: | Le facteur utilisé pour générer une date d'expiration en fonction de la date de dernière modification.
Syntaxe: | CacheLastModifiedFactor flottant
Défaut: | CacheLastModifiedFactor 0.1
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

Si un document ne possède pas de date d'expiration, elle peut être calculée en fonction de la date de dernière modification, si elle existe. La directive CacheLastModifiedFactor permet de spécifier un facteur à utiliser pour la génération de cette date d'expiration au sein de la formule suivante : délai-expiration = durée-depuis-date-dernière-modification * facteur date-expiration = date-courante + délai-expiration Par exemple, si la dernière modification du document date de 10 heures, et si facteur a pour valeur 0.1, le délai d'expiration sera de 10*0.1 = 1 heure. Si l'heure courante est 3:00pm, la date d'expiration calculée sera 3:00pm + 1 heure = 4:00pm. Si le délai d'expiration est supérieur à celui spécifié par la directive CacheMaxExpire, c'est ce dernier qui l'emporte.

CacheLastModifiedFactor 0.5

Directive CacheLock

Description: | Active la protection contre les tempêtes de requêtes.
Syntaxe: | CacheLock on|off
Défaut: | CacheLock off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache
Compatibilité: | Disponible depuis la version 2.2.15 d'Apache

La directive CacheLock active la protection contre les tempêtes de requêtes pour l'espace d'adressage donné.

La configuration minimale pour activer le verrouillage contre les tempêtes de requêtes dans le répertoire temp par défaut du système est la suivante :

# Active le verrouillage du cache
CacheLock on

Directive CacheLockMaxAge

Description: | Définit la durée de vie maximale d'un verrou de cache.
Syntaxe: | CacheLockMaxAge entier
Défaut: | CacheLockMaxAge 5
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache

La directive CacheLockMaxAge permet de spécifier la durée de vie maximale d'un verrou de cache.

Un verrou plus ancien que cette valeur exprimée en secondes sera ignoré, et la prochaine requête entrante sera alors en mesure de recréer le verrou. Ce mécanisme permet d'éviter les mises à jour trop longues initiées par des clients lents.

Directive CacheLockPath

Description: | Définit le répertoire des verrous.
Syntaxe: | CacheLockPath répertoire
Défaut: | CacheLockPath /tmp/mod_cache-lock
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache

La directive CacheLockPath permet de spécifier le répertoire dans lequel les verrous sont créés. Par défaut, c'est le répertoire temporaire du système qui est utilisé. Les verrous sont des fichiers vides qui n'existent que pour les URLs périmées en cours de mise à jour, et consomment donc bien moins de ressources que le traditionnel cache sur disque.

Directive CacheMaxExpire

Description: | La durée maximale en secondes de mise en cache d'un document
Syntaxe: | CacheMaxExpire secondes
Défaut: | CacheMaxExpire 86400 (une journée)
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

La directive CacheMaxExpire permet de spécifier le nombre maximum de secondes pendant lequel les documents HTTP suceptibles d'être mis en cache seront conservés sans vérifier leur contenu sur le serveur d'origine. Ce nombre de secondes correspond donc à la durée maximale pendant laquelle un document ne sera pas à jour. L'utilisation de cette valeur maximale est forcée, même si le document possède une date d'expiration.

CacheMaxExpire 604800

Directive CacheMinExpire

Description: | La durée minimale en secondes de mise en cache d'un document
Syntaxe: | CacheMinExpire secondes
Défaut: | CacheMinExpire 0
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

La directive CacheMaxExpire permet de spécifier le nombre maximum de secondes pendant lequel les documents HTTP suceptibles d'être mis en cache seront conservés sans vérifier leur contenu sur le serveur d'origine. Elle n'est prise en compte que dans le cas où le document ne possède aucune date d'expiration valide.

CacheMinExpire 3600

Directive CacheQuickHandler

Description: | Exécute le cache à partir d'un gestionnaire rapide.
Syntaxe: | CacheQuickHandler on|off
Défaut: | CacheQuickHandler on
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache
Compatibilité: | Disponible à partir de la version 2.3.3 du serveur HTTP Apache

La directive CacheQuickHandler permet de contrôler la phase au cours de laquelle la mise en cache est effectuée.

Avec la configuration par défaut, le cache agit au cours de la phase du gestionnaire rapide. Cette phase court-circuite la majorité des traitements du serveur, et constitue le mode d'opération le plus performant pour un serveur typique. Le cache s'incruste devant le serveur, et la majorité des traitements du serveur est court-circuitée.

Lorsque cette directive est définie à off, le cache agit comme un gestionnaire normal, et est concerné par toutes les phases de traitement d'une requête. Bien que ce mode soit moins performant que le mode par défaut, il permet d'utiliser le cache dans les cas où un traitement complet de la requête est nécessaire, comme par exemple lorsque le contenu est soumis à autorisation.

# Exécute le cache comme un gestionnaire normal
CacheQuickHandler off

Lorsque le gestionnaire rapide est désactivé, l'administrateur a aussi la possibilité de choisir avec précision le point de la chaîne de filtrage où la mise en cache sera effectuée, en utilisant le filtre CACHE.

# Mise en cache du contenu avant l'intervention de mod_include et
     # mod_deflate
CacheQuickHandler off
AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html

Si le filtre CACHE est spécifié plusieurs fois, c'est la dernière instance qui sera prise en compte.

Directive CacheStaleOnError

Description: | Sert du contenu non à jour à la place de réponses 5xx.
Syntaxe: | CacheStaleOnError on|off
Défaut: | CacheStaleOnError on
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache
Compatibilité: | Disponible depuis la version 2.3.9 d'Apache

Lorsque la directive CacheStaleOnError est définie à on, et si des données non mises à jour sont disponibles dans le cache, ce dernier renverra ces données, plutôt qu'une éventuelle réponse 5xx en provenance du serveur d'arrière-plan. Alors que l'en-tête Cache-Control envoyé par les clients sera respecté, et que les clients recevront donc dans ce cas la réponse 5xx brute à leur requête, cette réponse 5xx renvoyée au client n'invalidera pas le contenu dans le cache.

# Sert des données non mises à jour en cas d'erreur.
CacheStaleOnError on

Directive CacheStoreExpired

Description: | Tente de mettre en cache les réponses que le serveur considère comme arrivées à expiration
Syntaxe: | CacheStoreExpired On|Off
Défaut: | CacheStoreExpired Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

Depuis la version 2.2.4, les réponses qui sont arrivées à expiration ne sont pas stockées dans le cache. La directive CacheStoreExpired permet de modifier ce comportement. Avec CacheStoreExpired On, le serveur tente de mettre en cache la ressource si elle est périmée. Les requêtes suivantes vont déclencher une requête si-modifié-depuis de la part du serveur d'origine, et la réponse sera renvoyée à partir du cache si la ressource d'arrière-plan n'a pas été modifiée.

CacheStoreExpired On

Directive CacheStoreNoStore

Description: | Tente de mettre en cache les requêtes ou réponses dont l'entête Cache-Control: a pour valeur no-store.
Syntaxe: | CacheStoreNoStore On|Off
Défaut: | CacheStoreNoStore Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

Normalement, les requêtes ou réponses dont l'en-tête Cache-Control: a pour valeur no-store ne sont pas stockées dans le cache. La directive CacheStoreNoStore permet de modifier ce comportement. Si CacheStoreNoStore est définie à On, le serveur tente de mettre la ressource en cache même si elle contient des en-têtes ayant pour valeur no-store. Les ressources nécessitant une autorisation ne sont jamais mises en cache.

CacheStoreNoStore On

Avertissement :

Selon la RFC 2616, la valeur d'en-tête no-store est censée "prévenir la suppression ou la rétention par inadvertance d'informations sensibles (par exemple, sur des bandes de sauvegarde)". Autrement dit, l'activation de la directive CacheStoreNoCache pourrait provoquer le stockage d'informations sensibles dans le cache. Vous avez donc été prévenus.

Voir aussi

  • CacheIgnoreCacheControl
  • CacheStorePrivate

Directive CacheStorePrivate

Description: | Tente de mettre en cache des réponses que le serveur a marquées comme privées
Syntaxe: | CacheStorePrivate On|Off
Défaut: | CacheStorePrivate Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache

Normalement, les réponse comportant un en-tête Cache-Control: dont la valeur est private ne seront pas stockées dans le cache. La directive CacheStorePrivate permet de modifier ce comportement. Si CacheStorePrivate est définie à On, le serveur tentera de mettre la ressource en cache, même si elle contient des en-têtes ayant pour valeur private. Les ressources nécessitant une autorisation ne sont jamais mises en cache.

CacheStorePrivate On

Avertissement :

Cette directive autorise la mise en cache même si le serveur indique que la ressource ne doit pas être mise en cache. Elle n'est de ce fait appropriée que dans le cas d'un cache 'privé'.

Voir aussi

  • CacheIgnoreCacheControl
  • CacheStoreNoStore


mod_cache_disk - Serveur Apache HTTP Version 2.4

Module Apache mod_cache_disk

Description: | Module de stockage sur disque pour le filtre de mise en cache HTTP.
Statut: | Extension
Identificateur de Module: | cache_disk_module
Fichier Source: | mod_cache_disk.c

Sommaire

mod_cache_disk implémente un gestionnaire de stockage sur disque pour le module mod_cache.

Les en-têtes et corps des réponses mises en cache sont stockés séparément sur le disque, dans une structure de répertoires basée sur le condensé md5 de l'URL mise en cache.

Plusieurs réponses au contenu négocié peuvent être stockées en même temps, mais la mise en cache de contenus partiels n'est pas supportée actuellement par ce module.

Les mises à jour atomiques du cache pour les fichiers d'en-tête et de corps peuvent être effectuées sans verrouillage en enregistrant les numéros d'inode et de périphérique du fichier de corps dans le fichier d'en-tête. Ceci implique que les entrées du cache déplacées manuellement dans le cache seront ignorées.

L'utilitaire htcacheclean permet de lister et de supprimer les URLs du cache, ou de maintenir le cache en deçà de certaines limites de taille et/ou de nombre d'inodes. L'utilitaire peut être exécuté à la demande, ou automatiquement pour assurer un contrôle continu des tailles des répertoires.

Note :

mod_cache doit être chargé avant mod_cache_disk pour que ce dernier puisse fonctionner.

Note :

Lorsque la plate-forme la supporte, et si elle est activée via la directive EnableSendfile, mod_cache_disk utilise la fonctionnalité sendfile pour servir les fichiers à partir du cache. Cependant, mod_cache_disk ignore la configuration de la directive EnableSendfile dans un contexte de répertoire ou de fichier .htaccess, car le module ne dispose pas des définitions correspondantes lorsque la requête est servie depuis le cache.

Traitement des bugs

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

Voir aussi

  • mod_cache
  • mod_cache_socache
  • Guide de la mise en cache

Directive CacheDirLength

Description: | Le nombre de caractères des noms des sous-répertoires
Syntaxe: | CacheDirLength longueur
Défaut: | CacheDirLength 2
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache_disk

la directive CacheDirLength permet de définir le nombre de caractères que comportera chaque nom de sous-répertoire de la hiérarchie du cache. On peut l'utiliser en conjonction avec CacheDirLevels pour déterminer une structure approximative de la hiérarchie de cache.

Une valeur haute pour CacheDirLength combinée avec une valeur basse pour CacheDirLevels générera une hiérarchie relativement peu profonde, avec un grand nombre de sous-répertoires à chaque niveau.

La valeur du produit CacheDirLevels * CacheDirLength ne doit pas dépasser 20.

Directive CacheDirLevels

Description: | Le nombre de niveaux de sous-répertoires que comportera le cache.
Syntaxe: | CacheDirLevels niveaux
Défaut: | CacheDirLevels 2
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache_disk

La directive CacheDirLevels permet de définir le nombre de niveaux de sous-répertoires que comportera le cache. Les données du cache seront stokées au niveau correspondant par rapport au répertoire CacheRoot.

Une valeur haute pour CacheDirLevels combinée avec une valeur basse pour CacheDirLength générera une arborescence très développée, avec un petit nombre de sous-répertoires à chaque niveau.

La valeur du produit CacheDirLevels * CacheDirLength ne doit pas dépasser 20.

Directive CacheMaxFileSize

Description: | >La taille maximale (en octets) d'un document pour pouvoir être stocké dans le cache
Syntaxe: | CacheMaxFileSize octets
Défaut: | CacheMaxFileSize 1000000
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_disk

La directive CacheMaxFileSize permet de définir la taille maximale d'un document, en octets, pour que celui-ci puisse faire l'objet d'un stockage dans le cache.

CacheMaxFileSize 64000

Directive CacheMinFileSize

Description: | La taille minimale (en octets) d'un document pour pouvoir être stocké dans le cache
Syntaxe: | CacheMinFileSize octets
Défaut: | CacheMinFileSize 1
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_disk

La directive CacheMinFileSize permet de définir la taille minimale d'un document, en octets, pour que celui-ci puisse faire l'objet d'un stockage dans le cache.

CacheMinFileSize 64

Directive CacheReadSize

Description: | La quantité minimale (en octets) de données à lire et à mettre en cache avant de les envoyer au client
Syntaxe: | CacheReadSize octets
Défaut: | CacheReadSize 0
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_disk

La directive CacheReadSize permet de définir la quantité minimale de données, en octets, à lire depuis le serveur d'arrière-plan avant de les envoyer au client. Avec la valeur par défaut zéro, toute donnée de toutes tailles est envoyée au client dès qu'elle est disponible. Avec une valeur non nulle, le cache disque met en tampon au moins la quantité de données correspondante avant d'envoyer la réponse au client. Les performances peuvent s'en trouver améliorées lorsqu'on met en cache du contenu en provenance d'un mandataire inverse.

Cette directive ne prend effet que lorsque les données sont enregistrées dans le cache, et non lorsque les données sont servies à partir du cache.

CacheReadSize 102400

Directive CacheReadTime

Description: | Le temps minimum (en millisecondes) qui doit s'écouler avant d'envoyer les données au client
Syntaxe: | CacheReadTime millisecondes
Défaut: | CacheReadTime 0
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_disk

La directive CacheReadTime permet de définir le temps minimum qui doit s'écouler avant d'essayer d'envoyer des données au client. Pendant ce temps, les données sont mises en tampon avant de pouvoir être envoyées au client. Les performances peuvent s'en trouver améliorées lorsqu'on met en cache du contenu en provenance d'un mandataire inverse.

La valeur par défaut zéro désactive cette option.

Cette directive ne prend effet que lorsque les données sont enregistrées dans le cache, et non lorsque les données sont servies à partir du cache. Il est recommandé d'harmoniser l'utilisation de cette directive avec celle de la directive CacheReadSize, afin de s'assurer que le serveur n'effectue pas une mise en tampon excessive au cas où les données arriveraient plus vite que prévu.

CacheReadTime 1000

Directive CacheRoot

Description: | La racine du répertoire dans lequel les fichiers du cache seront stockés
Syntaxe: | CacheRoot répertoire
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache_disk

La directive CacheRoot permet de définir le nom du répertoire sur disque qui contiendra les fichiers du cache. Si le module mod_cache_disk a été chargé ou compilé dans le serveur Apache, cette directive doit être définie. L'absence de définition de la directive CacheRoot provoquera une erreur de traitement du fichier de configuration. Les directives CacheDirLevels et CacheDirLength permettent de définir la structure des sous-répertoires du répertoire racine spécifié.

CacheRoot c:/cacheroot


mod_cache_socache - Serveur Apache HTTP Version 2.4

Module Apache mod_cache_socache

Description: | Module de stockage à base de cache d'objets partagés (socache) pour le filtre de mise en cache HTTP.
Statut: | Extension
Identificateur de Module: | cache_socache_module
Fichier Source: | mod_cache_socache.c

Sommaire

Le module mod_cache_socache implémente un gestionnaire de stockage à base de cache d'objets partagés (socache) pour le module mod_cache.

Les en-têtes et corps des réponses mises en cache sont rassemblés et stockés sous une même clé dans le cache d'objets partagés. Il est possible de choisir entre plusieurs implémentations de caches d'objets partagés.

Des réponses avec différents contenus négociés peuvent être stockées simultanément ; cependant, la mise en cache de contenus partiels n'est pas encore supportée par ce module.

# Activation de la mise en cache
CacheSocache shmcb
CacheSocacheMaxSize 102400
<Location "/foo">
    CacheEnable socache
</Location>

# Possibilité de se rabattre sur le cache disque
CacheSocache shmcb
CacheSocacheMaxSize 102400
<Location "/foo">
    CacheEnable socache
    CacheEnable disk
</Location>

Note :

Le module mod_cache_socache requiert les services du module mod_cache qui doit donc avoir été préalablement chargé.

Traitement des bugs

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

Voir aussi

  • mod_cache
  • mod_cache_disk
  • Guide de la mise en cache

Directive CacheSocache

Description: | Implémentation du cache d'objets partagés à utiliser
Syntaxe: | CacheSocache type[:args]
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_cache_socache
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

La directive CacheSocache définit l'implémentation du cache d'objets partagés à utiliser, suivie d'arguments optionnels. Il est possible de choisir entre plusieurs implémentations de caches d'objets partagés.

CacheSocache shmcb

Directive CacheSocacheMaxSize

Description: | La taille maximale d'une entrée pouvant être placée dans le cache
Syntaxe: | CacheSocacheMaxSize octets
Défaut: | CacheSocacheMaxSize 102400
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_socache
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

La directive CacheSocacheMaxSize définit la taille maximale, en octets, de la somme des en-têtes et du corps d'un document pouvant être stocké dans le cache. Bien entendu, plus la taille des en-têtes sera grande, plus la taille maximale du corps du document s'en trouvera réduite.

Le module mod_cache_socache ne tentera de mettre en cache que des réponses qui possèdent une taille de contenu explicite, ou dont la taille est suffisamment petite pour qu'elles soient écrites en une seule passe. Ceci permet au module mod_cache_disk de mettre en cache des réponses dont la taille est trop importante pour pouvoir être mises en cache par mod_cache_socache.

CacheSocacheMaxSize 102400

Directive CacheSocacheMaxTime

Description: | La durée maximale de stockage d'un document dans le cache avant péremption
Syntaxe: | CacheSocacheMaxTime secondes
Défaut: | CacheSocacheMaxTime 86400
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_socache
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

La directive CacheSocacheMaxTime définit la durée de stockage maximale en secondes d'un document dans le cache avant péremption. Cette définition l'emporte sur la durée de fraîcheur définie pour le document par le protocole HTTP.

CacheSocacheMaxTime 86400

Directive CacheSocacheMinTime

Description: | La durée minimale de stockage d'un document dans le cache
Syntaxe: | CacheSocacheMinTime seconds
Défaut: | CacheSocacheMinTime 600
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_socache
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

La directive CacheSocacheMinTime définit le nombre de secondes au delà de la durée de fraîcheur de la réponse pendant lesquelles cette dernière devra être stockée dans le cache d'objets partagés. En effet, si une réponse n'est stockée que pour une durée égale à sa durée de fraîcheur, elle n'a pas besoin d'être rafraîchie.

CacheSocacheMinTime 600

Directive CacheSocacheReadSize

Description: | La quantité minimale de données du document à lire et mettre en cache avant envoi au client
Syntaxe: | CacheSocacheReadSize octets
Défaut: | CacheSocacheReadSize 0
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_socache
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

La directive CacheSocacheReadSize définit la quantité minimale de données, en octets, à lire depuis l'arrière-plan avant envoi au client. Avec la valeur par défaut 0, les données sont transmises au client dès leur arrivée et quelle que soit leur taille. Si la valeur définie est non nulle, le cache disque va mettre en tampon au moins la quantité de données correspondante avant envoi au client. Ceci peut améliorer les performances en cas de mise en cache de contenu en provenance d'un mandataire inverse lent.

Cette directive n'a d'effet qu'au moment où les données sont stockées dans le cache, et non lorsqu'elles sont servies depuis le cache.

CacheSocacheReadSize 102400

Directive CacheSocacheReadTime

Description: | La durée minimale de lecture avant l'envoi des données
Syntaxe: | CacheSocacheReadTime millisecondes
Défaut: | CacheSocacheReadTime 0
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_cache_socache
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

La directive CacheSocacheReadTime définit le temps minimal qui doit s'écouler avant de tenter l'envoi des données au client. Cette durée sera mise à profit pour lire et mettre en tampon les données avant leur envoi au client. Ceci peut améliorer les performances en cas de mise en cache de contenu en provenance d'un mandataire inverse.

La valeur par défaut 0 désactive cette directive.

Cette directive n'a d'effet qu'au moment où les données sont stockées dans le cache, et non lorsqu'elles sont servies depuis le cache. Il est recommandé d'utiliser cette directive en concomitance avec la directive CacheSocacheReadSize afin de s'assurer que le serveur ne mette pas les données en tampon de manière excessive dans le cas où les données arriveraient plus vite que prévu.

CacheSocacheReadTime 1000


mod_cern_meta - Serveur Apache HTTP Version 2.4

Module Apache mod_cern_meta

Description: | La sémantique des métafichiers du serveur httpd du CERN
Statut: | Extension
Identificateur de Module: | cern_meta_module
Fichier Source: | mod_cern_meta.c

Sommaire

Il s'agit d'une émulation de la sémantique des métafichiers du serveur httpd du CERN. Les métafichiers consistent en en-têtes HTTP qui peuvent s'ajouter au jeu d'en-têtes habituels pour chaque fichier accédé. Ils ressemblent beaucoup aux fichiers .asis d'Apache, et permettent d'influencer de manière rudimentaire l'en-tête Expires:, ainsi que d'autres curiosités. Il existe de nombreuses méthodes pour gérer les métainformations, mais le choix s'est porté sur celle-ci car il existe déjà un grand nombre d'utilisateurs du CERN qui peuvent exploiter ce module.

Pour plus d'information, voir le document sur la sémantique des métafichiers du CERN.

Traitement des bugs

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

Voir aussi

  • mod_headers
  • mod_asis

Directive MetaDir

Description: | Le nom du répertoire où trouver les fichiers de métainformations dans le style du CERN
Syntaxe: | MetaDir répertoire
Défaut: | MetaDir .web
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Extension
Module: | mod_cern_meta

Spécifie le nom du répertoire dans lequel Apache pourra trouver les fichiers de métainformations. Ce répertoire est en général un sous-répertoire 'caché' du répertoire qui contient le fichier à accéder. Définissez cette directive à "." pour rechercher les métafichiers dans le même répertoire que le fichier à accéder :

MetaDir .

Ou, pour rechercher dans un sous-répertoire du répertoire contenant le fichier à accéder :

MetaDir .meta

Directive MetaFiles

Description: | Active le traitement des métafichiers du CERN
Syntaxe: | MetaFiles on|off
Défaut: | MetaFiles off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Extension
Module: | mod_cern_meta

Active ou désactive le traitement des métafichiers pour certains répertoires.

Directive MetaSuffix

Description: | Suffixe du fichier contenant les métainformations dans le style du CERN
Syntaxe: | MetaSuffix suffixe
Défaut: | MetaSuffix .meta
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Extension
Module: | mod_cern_meta

Spécifie le suffixe du fichier contenant les métainformations. Par exemple, si on conserve les valeurs par défaut des deux directives précédentes, une requête pour DOCUMENT_ROOT/un-rep/index.html provoquera la recherche du métafichier DOCUMENT_ROOT/un-rep/.web/index.html.meta, et utilisera son contenu pour générer les informations quant aux en-têtes MIME additionnels.

Exemple :

MetaSuffix .meta


mod_cgi - Serveur Apache HTTP Version 2.4

Module Apache mod_cgi

Description: | Exécution des scripts CGI
Statut: | Base
Identificateur de Module: | cgi_module
Fichier Source: | mod_cgi.c

Sommaire

Tout fichier pris en compte par le gestionnaire cgi-script sera traité en tant que script CGI et exécuté par le serveur, sa sortie étant renvoyée au client. Les fichiers sont associés à ce gestionnaire soit parce qu'ils possèdent un nom contenant une extension définie par la directive AddHandler, soit parce qu'ils se situent dans un répertoire défini par une directive ScriptAlias.

Comme introduction à l'utilisation des scripts CGI avec Apache, voir notre tutoriel Les contenus dynamiques avec CGI.

Il est recommandé d'utiliser le module mod_cgid à la place de mod_cgi lorsqu'on utilise un module MPM multi-threadé sous Unix. Vus de l'utilisateur, les deux modules sont pratiquement identiques.

À des fins de compatibilité ascendante, le gestionnaire cgi-script sera aussi activé pour tout fichier possédant le type MIME application/x-httpd-cgi. L'utilisation du type MIME magic est obsolète.

Traitement des bugs

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

Voir aussi

  • AcceptPathInfo
  • Options ExecCGI
  • ScriptAlias
  • AddHandler
  • Exécuter des programmes CGI sous des utilisateurs différents
  • La spécification CGI

Les variables d'environnement CGI

Le serveur va définir les variables d'environnement CGI comme décrit dans la Spécification CGI, de la manière suivante :

PATH_INFO
Cette variable ne sera pas disponible si la directive AcceptPathInfo est explicitement définie à off. Par défaut, si la directive AcceptPathInfo n'est pas définie, mod_cgi acceptera des informations de chemin (en ajoutant /infos/chemin après le nom du script dans l'URI), alors que le serveur de base retournera une erreur 404 NOT FOUND pour les requêtes contenant des informations de chemin supplémentaires. Ne pas définir la directive AcceptPathInfo a le même effet sur les requêtes avec mod_cgi que de la définir à On.
REMOTE_HOST
Cette variable ne sera définie que si la directive HostnameLookups est définie à on (elle est à off par défaut), et si une recherche DNS inverse sur l'adresse IP de l'hôte client aboutit effectivement à un nom d'hôte.
REMOTE_IDENT
Cette variable ne sera définie que si la directive IdentityCheck est définie à on, et si l'hôte client supporte le protocole ident. Notez que l'on ne peut accorder une confiance aveugle au contenu de cette variable car il peut être aisément falsifié, et si un mandataire s'intercale entre le client et le serveur, il est totalement inutilisable.
REMOTE_USER
Cette variable ne sera définie que si le script CGI fait l'objet d'une authentification.

Ce module utilise aussi les fonctions de base ap_add_common_vars et ap_add_cgi_vars pour ajouter des variables d'environnement comme :

DOCUMENT_ROOT
Prend la valeur définie par la directive DocumentRoot.
SERVER_NAME
Le nom de domaine pleinement qualifié pour la requête considérée
SERVER_ADDR
L'adresse IP du serveur virtuel qui traite la requête
SERVER_ADMIN
Prend la valeur définie par la directive ServerAdmin.

Pour une liste exhaustive de ces variables, vous pouvez écrire un script CGI basique qui extrait toutes les variables d'environnement passées par Apache selon un format adapté.

Débogage des scripts CGI

Le débogage des scripts CGI était difficile par le passé, principalement parce qu'il n'était pas possible d'étudier la sortie (sortie standard et erreurs) des scripts dont l'exécution échouait. Les directives qui suivent permettent une journalisation plus détaillée des erreurs.

Format du fichier journal CGI

Lorsqu'il est configuré, le journal des erreurs CGI enregistre la sortie de tout programme CGI dont l'exécution ne s'effectue pas correctement. Un script CGI dont l'exécution échoue provoque la journalisation d'une grande quantité d'informations. Les deux premières lignes possèdent toujours le format suivant :

%% [date] requête
%% état HTTP nom du script CGI

Si le script CGI n'a pas pu démarrer, le fichier journal contiendra les deux lignes supplémentaires suivantes :

%%erreur
message d'erreur

Par contre, si l'erreur provient du renvoi par le script d'informations incorrectes dans les en-têtes (dû souvent à une bogue du script), les informations suivantes sont journalisées :

%requête
Tous les en-têtes de requête HTTP reçus
Les entités POST ou PUT (s'il en existe)
%réponse
Tous les en-têtes générés par le script CGI
%stdout
la sortie standard CGI
%stderr
la sortie d'erreurs standard CGI

(Les parties %stdout et %stderr seront absentes si le script n'a rien envoyé sur la sortie standard ou la sortie d'erreurs).

Directive ScriptLog

Description: | Chemin du fichier journal des erreurs du script CGI
Syntaxe: | ScriptLog chemin fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_cgi, mod_cgid

La directive ScriptLog permet de définir le chemin du fichier journal des erreurs du script CGI. Si cette directive n'est pas définie, aucune journalisation des erreurs n'est effectuée. Si elle est définie, toute erreur CGI sera enregistrée dans le fichier dont le nom est fourni en argument. S'il s'agit d'un chemin de fichier relatif, il est considéré par rapport au répertoire défini par la directive ServerRoot.

Exemple

ScriptLog logs/cgi_log

Ce journal sera ouvert par l'utilisateur sous lequel les processus enfants s'exécutent, c'est à dire l'utilisateur spécifié par la directive du serveur User. Ceci implique que le répertoire dans lequel se trouve le journal doit être accessible en écriture pour cet utilisateur, ou bien que le fichier est créé manuellement et accessible en écriture pour cet utilisateur. Si vous placez le journal du script dans votre répertoire principal des journaux, ne modifiez JAMAIS les permissions de ce dernier afin de le le rendre accessible en écriture par l'utilisateur sous lequel les processus enfants s'exécutent.

Notez que l'on ne doit activer la journalisation des scripts qu'à des fins de débogage lors de l'écriture de scripts CGI, et non de manière permanente sur un serveur en production. Elle n'est pas optimisée en terme de performances et d'efficacité, et peut présenter des problèmes de sécurité si on l'utilise dans un cadre autre que celui pour lequel elle a été conçue.

Directive ScriptLogBuffer

Description: | Taille maximale des requêtes PUT ou POST qui seront enregistrées dans le journal du script
Syntaxe: | ScriptLogBuffer octets
Défaut: | ScriptLogBuffer 1024
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_cgi, mod_cgid

Cette directive permet de limiter la taille du corps de toute entité PUT ou POST qui sera enregistrée dans le journal, afin de prévenir une croissance trop importante et trop rapide du fichier journal due à la réception de corps de requête de grandes tailles. Cette directive permet de modifier cette taille maximale, dont la valeur par défaut est de 1024 octets.

Directive ScriptLogLength

Description: | Taille maximale du fichier journal des scripts CGI
Syntaxe: | ScriptLogLength octets
Défaut: | ScriptLogLength 10385760
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_cgi, mod_cgid

La directive ScriptLogLength permet de définir la taille maximale du fichier journal des scripts CGI. Comme le fichier journal accumule une grande quantité d'informations par erreur CGI (tous les en-têtes de la requête, toutes les sorties du script), il peut vite atteindre une grande taille. En limitant la taille du fichier, cette directive permet d'éviter les problèmes que causerait sa croissance sans limites. Lorsque le fichier a atteint cette taille maximale, plus aucune information n'y est enregistrée.


mod_cgid - Serveur Apache HTTP Version 2.4

Module Apache mod_cgid

Description: | Exécution des scripts CGI par l'intermédiaire d'un démon CGI externe
Statut: | Base
Identificateur de Module: | cgid_module
Fichier Source: | mod_cgid.c
Compatibilité: | Uniquement compatible avec les MPMs Unix threadés

Sommaire

Exceptées les optimisations et la directive additionnelle ScriptSock décrite ci-dessous, mod_cgid a un comportement similaire à celui de mod_cgi. Voir le résumé de mod_cgi pour plus de détails à propos d'Apache et CGI.

Sur certains systèmes d'exploitation de type unix, le lancement (forking) d'un processus depuis un serveur multi-threadé est une opération très lourde car le nouveau processus va répliquer tous les threads du processus parent. Pour éviter cette dépense de ressouces pour chaque invocation d'un programme CGI, mod_cgid crée un démon externe qui est responsable du branchement de processus enfants destinés au lancement de scripts CGI. Le serveur principal communique avec ce démon par l'intermédiaire d'une socket de domaine unix.

Si un MPM multi-threadé a été sélectionné lors du processus de compilation, c'est ce module qui est utilisé par défaut à la place de mod_cgi. Du point de vue de l'utilisateur, ce module est identique à mod_cgi quant à sa configuration et son utilisation. La seule différence est la directive additionnelle ScriptSock qui permet de définir le nom du socket à utiliser pour la communication avec le démon CGI.

Traitement des bugs

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

Voir aussi

  • mod_cgi
  • Exécution de programmes CGI sous des utilisateurs différents

Directive CGIDScriptTimeout

Description: | Durée maximale d'attente de la prochaine sortie du programme CGI
Syntaxe: | CGIDScriptTimeout time[s|ms]
Défaut: | Valeur de la directive Timeout
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Base
Module: | mod_cgid
Compatibilité: | La valeur de CGIDScriptTimeout est 0 dans les versions 2.4 et antérieures

Cette directive permet de limiter la durée d'attente avant les prochaines données reçues en sortie du programme CGI. Si ce temps est dépassé, la requête et le programme CGI se terminent.

Exemple

CGIDScriptTimeout 20

Directive ScriptSock

Description: | Le préfixe du nom de fichier du socket à utiliser pour communiquer avec le démon CGI
Syntaxe: | ScriptSock chemin fichier
Défaut: | ScriptSock cgisock
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_cgid

Cette directive permet de définir le préfixe du nom de fichier de la socket à utiliser pour communiquer avec le démon CGI, préfixe auquel sera ajouté une extension correspondant à l'identifiant processus du serveur. La socket sera ouverte avec les permissions de l'utilisateur qui a démarré Apache (en général root). Afin de préserver la sécurité des communications avec les scripts CGI, il est impératif de n'accorder à aucun autre utilisateur la permission d'écrire dans le répertoire où se trouve la socket.

Si chemin fichier n'est pas un chemin absolu, il est relatif au chemin défini par la directive DefaultRuntimeDir.

Exemple

ScriptSock /var/run/cgid.sock


mod_charset_lite - Serveur Apache HTTP Version 2.4

Module Apache mod_charset_lite

Description: | Spécifie dans quel jeu de caractère doivent s'effectuer les traductions ou les réencodages
Statut: | Extension
Identificateur de Module: | charset_lite_module
Fichier Source: | mod_charset_lite.c

Sommaire

Le module mod_charset_lite permet au serveur de modifier le jeu de caractères des réponses avant de les envoyer aux clients. Dans un environnement EBCDIC, Apache traduit toujours les contenus au protocole HTTP (par exemples les en-têtes de réponses) de la page de code de la locale du processus Apache vers ISO-8859-1, mais pas le corps des réponses. Dans tous les environnements, on peut utiliser mod_charset_lite pour spécifier que les corps des réponses doivent être traduits. Par exemple, si les fichiers sont stockés sous forme EBCDIC, mod_charset_lite pourra les traduire en ISO-8859-1 avant de les envoyer au client.

Ce module fournit quelques procédés de configuration implémentés par Apache version russe, ainsi que son module mod_charset associé.

Problèmes courants

Noms de jeux de caractères non valides

Les noms des jeux de caractères passés en paramètres aux directives CharsetSourceEnc et CharsetDefault doivent être reconnus par le mécanisme de traduction utilisé par APR sur le système où mod_charset_lite est utilisé. Ces noms de jeux de caractères ne sont pas standardisés, et sont en général différents des valeurs qui leur correspondent dans les en-têtes HTTP. Actuellement, APR ne peut utiliser que iconv(3) ; vous pouvez donc tester facilement vos noms de jeux de caractères en utilisant le programme iconv(1), de la manière suivante :

iconv -f valeur-charsetsourceenc -t valeur-charsetdefault

Incompatibilité entre le jeu de caractères du contenu et les règles de traduction

Si les règles de traduction ne peuvent s'appliquer au contenu, la traduction peut échouer avec des conséquences diverses, comme :

  • Le mécanisme de traduction peut renvoyer un mauvais code de retour, et la connexion sera interrompue.
  • Le mécanisme de traduction peut insérer silencieusement des caractères spéciaux (par exemple des points d'interrogation) dans le tampon de sortie lorsqu'il n'est pas en mesure de traduire le tampon d'entrée.

Directive CharsetDefault

Description: | Jeu de caractère vers lequel la traduction doit s'effectuer
Syntaxe: | CharsetDefault jeu de caractères
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_charset_lite

La directive CharsetDefault permet de spécifier le jeu de caractères vers lequel le contenu situé dans le conteneur associé devra être traduit.

La valeur de l'argument jeu de caractères doit être un nom de jeu de caractères valide du point de vue du support des jeux de caractères dans APR. En général, cela implique qu'elle doit être reconnue par iconv.

Exemple

<Directory "/export/home/trawick/apacheinst/htdocs/convert">
    CharsetSourceEnc  UTF-16BE
    CharsetDefault    ISO-8859-1
</Directory>
Spécifier le même jeu de caractères pour les deux directives CharsetSourceEnc et CharsetDefault désactive la traduction. Le jeu de caractères ne doit pas forcément correspondre au jeu de caractères de la réponse, mais il doit être valide du point de vue du système.

Directive CharsetOptions

Description: | Précise les détails de la traduction du jeu de caractères
Syntaxe: | CharsetOptions option [option] ...
Défaut: | CharsetOptions ImplicitAdd
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_charset_lite

La directive CharsetOptions permet de préciser certains détails du comportement du module mod_charset_lite. Option accepte les valeurs suivantes :

ImplicitAdd | NoImplicitAdd
Le mot-clé ImplicitAdd indique que mod_charset_lite doit insérer son filtre de manière implicite lorsque la configuration indique que le jeu de caractère du contenu doit être traduit. Si la chaîne de filtrage est configurée de manière explicite via la directive AddOutputFilter, l'option NoImplicitAdd doit être utilisée afin que mod_charset_lite n'ajoute pas son propre filtre.
TranslateAllMimeTypes | NoTranslateAllMimeTypes
Normalement, mod_charset_lite n'effectuera une traduction qu'en présence d'un petit nombre de types MIME parmi tous les types possibles. Lorsque l'option TranslateAllMimeTypes est utilisée pour une section de configuration donnée, la traduction est effectuée sans se préoccuper du type MIME.

Directive CharsetSourceEnc

Description: | Jeu de caractères source des fichiers
Syntaxe: | CharsetSourceEnc jeu de caractères
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_charset_lite

La directive CharsetSourceEnc permet de spécifier un jeu de caractères source pour les fichiers situés dans le conteneur associé.

La valeur de l'argument jeu de caractères doit être un nom de jeu de caractères valide du point de vue du support des jeux de caractères dans APR. En général, cela implique qu'elle doit être reconnue par iconv.

Exemple

<Directory "/export/home/trawick/apacheinst/htdocs/convert">
    CharsetSourceEnc  UTF-16BE
    CharsetDefault    ISO-8859-1
</Directory>

Les noms de jeux de caractères de cet exemple sont reconnus par le mécanisme de traduction d'iconv sous Solaris 8.

Spécifier le même jeu de caractères pour les deux directives CharsetSourceEnc et CharsetDefault désactive la traduction. Le jeu de caractères ne doit pas forcément correspondre au jeu de caractères de la réponse, mais il doit être valide du point de vue du système.


mod_data - Serveur Apache HTTP Version 2.4

Module Apache mod_data

Description: | Convertit un corps de réponse en URL de type données RFC2397
Statut: | Extension
Identificateur de Module: | data_module
Fichier Source: | mod_data.c
Compatibilité: | Disponible depuis la version 2.3 du serveur HTTP Apache

Sommaire

Ce module permet de convertir une réponse en URL de type données RFC2397.

Les URLs de type données peuvent être incluses en ligne dans les pages web via le module mod_include par exemple, afin d'éviter aux clients d'avoir à effectuer des connexions séparées pour éventuellement extraire un grand nombre de petites images. Les URLs de type données peuvent aussi être incluses dans des pages générées par langages de scripting tels que PHP.

Un exemple d'URL de type données

data:image/gif;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAw
AAAC8IyPqcvt3wCcDkiLc7C0qwyGHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFz
ByTB10QgxOR0TqBQejhRNzOfkVJ+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSp
a/TPg7JpJHxyendzWTBfX0cxOnKPjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJl
ZeGl9i2icVqaNVailT6F5iJ90m6mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uis
F81M1OIcR7lEewwcLp7tuNNkM3uNna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PH
hhx4dbgYKAAA7

Le filtre n'accepte aucun paramètre, et peut être ajouté à la pile des filtres via la directive SetOutputFilter, ou toute autre directive supportée par le module mod_filter.

Configuration du filtre

<Location "/data/images">
    SetOutputFilter DATA
</Location>

Traitement des bugs

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

Voir aussi

  • Les filtres


mod_dav - Serveur Apache HTTP Version 2.4

Module Apache mod_dav

Description: | Fonctionnalité de création et gestion de versions de documents via le web (WebDAV)
Statut: | Extension
Identificateur de Module: | dav_module
Fichier Source: | mod_dav.c

Sommaire

Ce module ajoute à Apache une fonctionnalité WebDAV de classes 1 et 2 ('Web-based Distributed Authoring and Versioning' ou Création et gestion de versions de documents via le web). Il s'agit d'une extension du protocole HTTP qui permet de créer, déplacer, copier et supprimer des ressources ou collections de ressources sur un serveur web distant.

Traitement des bugs

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

Voir aussi

  • DavLockDB
  • LimitXMLRequestBody
  • Ressources WebDAV

Activation de WebDAV

Pour activer le module mod_dav, ajoutez la ligne suivante à un conteneur de votre fichier httpd.conf :

Dav On

Ceci active le fournisseur de système de fichier DAV implémenté par le module mod_dav_fs. Ce dernier doit donc être compilé dans le serveur ou chargé au démarrage à l'aide de la directive LoadModule.

En outre, vous devez indiquer où se trouve la base de données des verrous DAV via une directive DavLockDB dans la section globale de votre fichier httpd.conf :

DavLockDB /usr/local/apache2/var/DavLock

Le répertoire contenant le fichier de la base de données des verrous doit avoir des droits en écriture pour l'utilisateur et le groupe sous lesquels Apache s'exécute et définis respectivement par les directives User et Group.

Si vous souhaitez limiter l'accès aux répertoires où DAV est activé, vous pouvez ajouter une clause <Limit> dans la section <Location> considérée. Pour définir la quantité maximale de données en octets qu'un client DAV peut envoyer par requête, vous devez utiliser la directive LimitXMLRequestBody, car La directive LimitRequestBody "habituelle" n'a aucune incidence sur les requêtes DAV.

Exemple complet

DavLockDB "/usr/local/apache2/var/DavLock"

<Directory "/usr/local/apache2/htdocs/foo">
    Require all granted
    Dav On

    AuthType Basic
    AuthName DAV
    AuthUserFile "user.passwd"

    <LimitExcept GET POST OPTIONS>
        Require user admin
    </LimitExcept>
</Directory>

Problèmes concernant la sécurité

Etant donné que les méthodes d'accès DAV permettent à des clients distants de manipuler des fichiers sur le serveur, vous devez vous assurer que votre serveur est bien sécurisé avant d'activer mod_dav.

Tout répertoire du serveur où DAV est activé doit être protégé par une procédure d'authentification. L'utilisation de l'authentification HTTP de base n'est pas recommandée. Vous devez utiliser au moins l'authentification HTTP à base de condensés qu'implémente le module mod_auth_digest. Pratiquement tous les clients WebDAV supportent cette méthode d'authentification. Vous pouvez aussi utiliser l'authentification de base sur une connexion où SSL est activé.

Pour que mod_dav puisse manipuler des fichiers, il doit avoir des permissions en écriture sur les répertoires et les fichiers qui sont sous son contrôle ; en d'autre termes, c'est l'utilisateur et le groupe sous lesquels Apache s'exécute et définis par les directives User et Group qui doivent avoir les droits en écriture sur ces fichiers et répertoires. Les fichiers nouvellement créés appartiendront aussi à ces utilisateur et groupe. Par conséquent, il est important de contrôler l'accès à ce compte. Les répertoires DAV sont considérés comme privés du point de vue d'Apache, et la modification des fichiers qu'ils contiennent autrement que par l'intermédiaire d'Apache (par exemple par FTP ou par des outils du niveau du système de fichiers) ne doit pas être permise.

mod_dav peut faire l'objet de plusieurs sortes d'attaques par déni de service. La directive LimitXMLRequestBody permet de limiter la quantité de mémoire consommée pour interpréter des requêtes DAV de grande taille. En outre, la directive DavDepthInfinity permet d'empêcher les requêtes PROPFIND concernant un répertoire de très grande taille de consommer de grandes quantités de mémoire. Un autre type d'attaque par déni de service peut aussi être mené par un client qui remplit simplement tout l'espace disque disponible avec des fichiers de très grande taille. Etant donné qu'il n'existe aucun moyen direct d'éviter ce genre d'attaque dans Apache, vous ne devez accorder des accès DAV qu'à des utilisateurs de confiance.

Configurations complexes

Les requêtes ayant pour but de manipuler des fichiers dynamiques (scripts PHP, scripts CGI, etc...) en utilisant mod_dav sont courantes. Ce traitement n'est pas évident car une requête GET va toujours tenter d'exécuter le script, plutôt que de télécharger son contenu. Pour éviter cet inconvénient, une méthode possible consiste à faire correspondre deux URLs différentes au même contenu, l'une d'entre elles servant à lancer le script, alors que l'autre peut être utilisée pour le télécharger et le manipuler avec DAV.

Alias "/phparea" "/home/gstein/php_files"
Alias "/php-source" "/home/gstein/php_files"
<Location "/php-source">
Dav On
ForceType text/plain
</Location>

Avec cette configuration, on peut utiliser http://example.com/phparea pour afficher le résultat de l'exécution des scripts PHP, et http://example.com/php-source pour les manipuler avec DAV.

Directive Dav

Description: | Active les méthodes HTTP WebDAV
Syntaxe: | Dav On|Off|nom fournisseur
Défaut: | Dav Off
Contexte: | répertoire
Statut: | Extension
Module: | mod_dav

La directive Dav permet d'activer les méthodes HTTP WebDAV pour le conteneur condidéré :

<Location "/foo">
    Dav On
</Location>

La valeur On est en fait un alias vers le fournisseur par défaut filesystem implémenté par le module mod_dav_fs. Notez que lorsque DAV est activé pour un conteneur, on ne peut pas le désactiver pour ses sous-conteneurs. Pour un exemple de configuration complet, reportez-vous à la section précédente.

N'activez pas WebDAV tant que votre serveur n'est pas sécurisé. Si vous passez outre cette recommandation, tout le monde pourra enregistrer des fichiers sur votre système.

Directive DavDepthInfinity

Description: | Autorise les requêtes PROPFIND avec en-tête Depth: Infinity
Syntaxe: | DavDepthInfinity on|off
Défaut: | DavDepthInfinity off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_dav

La directive DavDepthInfinity permet d'autoriser le traitement des requêtes PROPFIND contenant l'en-tête Depth: Infinity. Par défaut, ce type de requête n'est pas autorisé, car il peut favoriser les attaques de type Déni de service.

Directive DavMinTimeout

Description: | Durée minimale pendant laquelle le serveur maintient un verrou sur une ressource DAV
Syntaxe: | DavMinTimeout secondes
Défaut: | DavMinTimeout 0
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_dav

Lorsqu'un client demande le verrouillage d'une ressource DAV, il peut aussi spécifier une durée au bout de laquelle le verrou sera automatiquement supprimé par le serveur. Cette valeur ne constitue qu'une demande, et le serveur peut l'ignorer ou informer le client qu'il va utiliser une valeur arbitraire.

La directive DavMinTimeout permet de spécifier, en secondes, la durée minimale de verrouillage à renvoyer au client. Les Répertoires Web de Microsoft présentent une durée par défaut de 120 secondes ; la directive DavMinTimeout permet de définir une valeur supérieure (par exemple 600 secondes), afin de réduire les risques de perte du verrou par le client suite à une surcharge du réseau.

Exemple

<Location "/MSWord">
    DavMinTimeout 600
</Location>


mod_dav_fs - Serveur Apache HTTP Version 2.4

Module Apache mod_dav_fs

Description: | Implémente le fournisseur filesystem pour mod_dav
Statut: | Extension
Identificateur de Module: | dav_fs_module
Fichier Source: | mod_dav_fs.c

Sommaire

L'activation de ce module nécessite l'utilisation de mod_dav. C'est un module de support pour mod_dav et à ce titre, il permet l'accès à des ressources situées dans le système de fichiers du serveur. Le nom formel de ce fournisseur est filesystem. Les fournisseurs supports de mod_dav sont invoqués via la directive Dav :

Exemple

Dav filesystem

Comme filesystem est le fournisseur par défaut de mod_dav, vous pouvez vous contenter d'utiliser la valeur On comme argument de Dav.

Traitement des bugs

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

Voir aussi

  • mod_dav

Directive DavLockDB

Description: | Chemin de la base de données des verrous DAV
Syntaxe: | DavLockDB chemin fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dav_fs

La directive DavLockDB permet de spécifier le chemin complet de la base de données des verrous, sans extension. Si le chemin n'est pas absolu, il sera considéré comme relatif au répertoire défini par la directive ServerRoot. L'implémentation de mod_dav_fs utilise une base de données SDBM pour surveiller les verrous utilisateurs.

Exemple

DavLockDB "var/DavLock"

Les utilisateur et groupe sous lesquels Apache s'exécute et qui sont respectivement définis par les directives User et Group doivent pouvoir écrire dans le répertoire qui contient le fichier de la base de données des verrous. Pour des raisons de sécurité, il est recommandé de créer un répertoire dédié à la base de données des verrous, plutôt que de modifier les permissions d'un répertoire existant. Dans l'exemple ci-dessus, Apache va créer des fichiers dans le répertoire var/, lui-même sous-répertoire du répertoire défini par la directive ServerRoot, avec le nom de base DavLock suivi d'une extension choisie par le serveur.


mod_dav_lock - Serveur Apache HTTP Version 2.4

Module Apache mod_dav_lock

Description: | Module de verrouillage générique pour mod_dav
Statut: | Extension
Identificateur de Module: | dav_lock_module
Fichier Source: | mod_dav_lock.c
Compatibilité: | Disponible depuis la version 2.1 d'Apache

Sommaire

ce module implémente une API de verrouillage générique que tout fournisseur support de mod_dav peut utiliser. Son activation nécessite l'utilisation de mod_dav. Mais sans fournisseur support pour l'utiliser, il n'est d'aucun service et ne doit pas être chargé dans le serveur. mod_dav_svn, le module qui implémente le fournisseur subversion, est un exemple de module de support qui utilise effectivement mod_dav_lock.

Notez que mod_dav_fs n'a pas besoin de ce module de verrouillage générique, car il utilise sa propre version plus spécifique.

Pour que mod_dav_lock puisse fonctionner, il vous suffit de spécifier le chemin de la base de données des verrous à l'aide de la directive DavGenericLockDB décrite ci-dessous.

Note du développeur

Pour déterminer le pointeur de la fonction du fournisseur de verrouillage, vous devez utiliser l'API ap_lookup_provider avec les arguments dav-lock, generic et 0.

Traitement des bugs

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

Voir aussi

  • mod_dav

Directive DavGenericLockDB

Description: | Chemin de la base de données des verrous DAV
Syntaxe: | DavGenericLockDB chemin fichier
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_dav_lock

La directive DavLockDB permet de spécifier le chemin complet de la base de données des verrous, sans extension. Si le chemin n'est pas absolu, il sera considéré comme relatif au répertoire défini par la directive ServerRoot. L'implémentation de mod_dav_lock utilise une base de données SDBM pour surveiller les verrous utilisateurs.

Exemple

DavGenericLockDB var/DavLock

Les utilisateur et groupe sous lesquels Apache s'exécute et qui sont respectivement définis par les directives User et Group doivent pouvoir écrire dans le répertoire qui contient le fichier de la base de données des verrous. Pour des raisons de sécurité, il est recommandé de créer un répertoire dédié à la base de données des verrous, plutôt que de modifier les permissions d'un répertoire existant. Dans l'exemple ci-dessus, Apache va créer des fichiers dans le répertoire var/, lui-même sous-répertoire du répertoire défini par la directive ServerRoot, avec le nom de base DavLock suivi d'une extension choisie par le serveur.


mod_dbd - Serveur Apache HTTP Version 2.4

Module Apache mod_dbd

Description: | Gestion des connexions à une base de données SQL
Statut: | Extension
Identificateur de Module: | dbd_module
Fichier Source: | mod_dbd.c
Compatibilité: | Versions 2.1 and supérieures

Sommaire

Le module mod_dbd gère les connexions à une base de données SQL via APR. Il permet aux modules qui requièrent des fonctions liées aux bases de données SQL de se connecter à une base de données à la demande, et s'efforce de conférer aux bases de données une efficacité et une évolutivité optimales pour les MPMs threadés ou non threadés. Pour plus de détails, voir le site web APR, ainsi que cette vue d'ensemble de l'environnement de développement d'Apache DBD par son développeur initial.

Traitement des bugs

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

Voir aussi

  • Formats des mots de passe

Regroupement des connexions

Ce module gère de manière optimisée en fonction de la plate-forme les connexions aux bases de données. Sur les plates-formes non threadées, il maintient une connexion persistente à la manière d'un LAMP classique (Linux, Apache, Mysql, Perl/PHP/Python). Sur les plates-formes threadées, il maintient un groupe de connexions à la fois plus évolutif et plus efficace, comme décrit dans cet article d'ApacheTutor. Notez que mod_dbd remplace les modules présentés dans cet article.

Connexion

Pour vous connecter à votre base de données, vous devez spécifier un pilote et des paramètres de connexion qui diffèrent selon le moteur de base de données. Par exemple, pour vous connecter à mysql, spécifiez ce qui suit :

DBDriver mysql
DBDParams host=localhost,dbname=pony,user=shetland,pass=appaloosa

Vous pourrez alors utiliser cette connexion dans de nombreux autres modules comme mod_rewrite, mod_authn_dbd et mod_lua. Vous trouverez des exemples d'utilisation dans la documentation de ces modules.

Voir la syntaxe de la directive DBDParams pour les informations à fournir dans la chaîne de connexion en fonction des différents pilotes de base de données supportés.

API DBD d'Apache

mod_dbd exporte cinq fonctions que d'autres modules pourront utiliser. L'API se présente comme suit :

typedef struct {
    apr_dbd_t *handle;
    apr_dbd_driver_t *driver;
    apr_hash_t *prepared;
} ap_dbd_t;

/* Fonctions exportées pour accéder à la base de données */

/* ouvre une connexion qui DOIT avoir été explicitement fermée.
 * Renvoie NULL en cas d'erreur
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);

/* ferme une connexion ouverte avec ap_dbd_open */
AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);

/* acquiert une connexion qui aura la durée de vie de la requête et qui
 * NE DOIT PAS avoir été explicitement fermée. Renvoie NULL en cas
 * d'erreur. C'est la fonction recommandée pour la plupart des
 * applications.
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);

/* acquiert une connexion qui aura la durée de vie d'une connexion et
 * qui NE DOIT PAS avoir été explicitement fermée. Renvoie NULL en cas
 * d'erreur.
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);

/* Prépare une requête qu'un module client pourra utiliser */
AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);

/* Exporte aussi ces fonctions à titre optionnel mour les modules qui
 * péfèreraient les utiliser */
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));

Requêtes SQL préparées

mod_dbd supporte les requêtes SQL préparées à destination des modules qui pourraient les utiliser. Chaque requête préparée doit posséder un nom (étiquette), et est stockée dans un condensé (hash) : les condensés sont du type apr_dbd_prepared_t et s'utilisent dans toute requête SQL ou commande select préparée par apr_dbd.

Il est du ressort des modules utilisateurs de dbd d'utiliser les requêtes préparées et de préciser quelles requêtes doivent être spécifiées dans httpd.conf, ou de fournir leurs propres directives et d'utiliser ap_dbd_prepare.

Avertissement

Lorsqu'on utilise des requêtes préparées avec des bases de données MySQL, il est préférable de définir reconnect à 0 dans la chaîne de connexion, afin d'éviter des erreurs provoquées par un client MySQL qui se reconnecterait sans réinitialiser correctement les requêtes préparées. Si reconnect est défini à 1, toute connexion défectueuse sera sensée être réparée, mais comme mod_dbd n'en est pas informé, les requêtes préparées seront invalidées.

AVERTISSEMENT DE SECURITE

Toute application web impliquant une base de données doit se protéger elle-même contre les attaques de type injection SQL. Dans la plupart des cas Apache DBD est sûr, car les applications utilisent des requêtes préparées, et les entrées non sures ne seront utilisées qu'à titre de données. Bien entendu, si vous l'utilisez via un module tiers, vous devez être au fait des précautions à prendre.

Cependant, le pilote FreeTDS est non sûr de par sa nature-même. Comme la bibliothèque sous-jacente ne supporte pas les requêtes préparées, le pilote en effectue une émulation, et les entrées non sûres sont fusionnées avec la requête SQL.

Il peut être sécurisé en décontaminant toutes les entrées : un processus inspiré de la recherche de contaminations (taint mode) de Perl. Chaque entrée est comparée à une expression rationnelle, et seules les entrées qui correspondent sont utilisées, en accord avec le langage Perl :

  $untrusted =~ /([a-z]+)/;
  $trusted = $1;

Pour utiliser ceci, les expressions rationnelles de décontamination doivent être incluses dans les requêtes préparées. L'expression rationnelle doit se situer immédiatement après le caractère % dans la requête préparée, et doit être entourée d'accolades {}. Par exemple, si votre application attend une entrée alphanumérique, vous pouvez utiliser :

"SELECT foo FROM bar WHERE input = %s"

avec d'autres pilotes, et ne risquer au pire qu'une requête échouée. Mais avec FreeTDS, vous devez utiliser :

"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"

tout ce qui ne correspond pas à l'expression rationnelle est alors rejeté, et la requête est maintenant sûre.

Alternativement, vous pouvez utiliser le pilote ODBC tiers, qui offre la sécurité des requêtes préparées authentiques.

Directive DBDExptime

Description: | Durée de vie des connexions inactives
Syntaxe: | DBDExptime durée en secondes
Défaut: | DBDExptime 300
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Cette directive permet de définir la durée de vie des connexions inactives lorsque le nombre de connexions spécifié par la directive DBDKeep a été dépassé (plates-formes threadées uniquement).

Directive DBDInitSQL

Description: | Exécute une instruction SQL après connexion à une base de données
Syntaxe: | DBDInitSQL "instruction SQL"
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Les modules qui le souhaitent peuvent exécuter une ou plusieurs instructions SQL après connexion à une base de données. Par exemple initialiser certaines valeurs, ou ajouter une entrée dans le journal lors d'une nouvelle connexion à la base de données.

Directive DBDKeep

Description: | Nombre maximum de connexions maintenues
Syntaxe: | DBDKeep nombre
Défaut: | DBDKeep 2
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Cette directive permet de définir le nombre maximum de connexions à maintenir par processus, en dehors de celles servant à gérer les pics de demandes (plates-formes threadées uniquement).

Directive DBDMax

Description: | Nombre maximum de connexions
Syntaxe: | DBDMax nombre
Défaut: | DBDMax 10
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Cette directive permet de définir le nombre maximum effectif de connexions par processus (plates-formes threadées uniquement).

Directive DBDMin

Description: | Nombre minimum de connexions
Syntaxe: | DBDMin nombre
Défaut: | DBDMin 1
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Cette directive permet de définir le nombre minimum de connexions par processus (plates-formes threadées uniquement).

Directive DBDParams

Description: | Paramètres de la connexion à la base de données
Syntaxe: | DBDParams param1=valeur1[,param2=valeur2]
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Cette directive permet de spécifier des paramètres selon les besoins du pilote concerné. En général, les paramètres à passer concernent tout ce qui n'a pas de valeur par défaut comme le nom d'utilisateur, le mot de passe, le nom de la base de données, le nom d'hôte et le numéro de port de la connexion.

Les paramètres de la chaîne de connexion en fonction des différents pilotes comprennent :

FreeTDS (pour MSSQL et SyBase)
username, password, appname, dbname, host, charset, lang, server
MySQL
host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect
Oracle
user, pass, dbname, server
PostgreSQL
La chaîne de connexion est passée directement à PQconnectdb
SQLite2
La chaîne de connexion est scindée avec comme séparateur le caractère ':', et partie1:partie2 est utilisé dans sqlite_open(partie1, atoi(partie2), NULL)
SQLite3
La chaîne de connexion est passée directement à sqlite3_open
ODBC
datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize

Directive DBDPersist

Description: | Utiliser ou non des connexions persistentes
Syntaxe: | DBDPersist On|Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Si cette directive est définie à Off, les connexions persistentes et les connexions groupées sont désactivées. À la demande d'un client, une nouvelle connexion à la base de données est ouverte, et fermée immédiatement à l'issue du traitement. Cette configuration ne doit être utilisée qu'à des fins de débogage, ou sur des serveurs à charge faible.

Par défaut, les groupes de connexions persistentes sont activés (ou une seule connexion persistente du style LAMP pour les serveurs non threadés), et c'est la configuration qui devrait être utilisée dans la plupart des cas sur un serveur en production.

Avant la version 2.2.2, cette directive n'acceptait que les valeurs 0 et 1 au lieu de Off et On, respectivement.

Directive DBDPrepareSQL

Description: | Définit une requête SQL préparée
Syntaxe: | DBDPrepareSQL "requête SQL" étiquette
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Pour les modules tels que les modules d'authentification, qui utilisent de manière répétée la même requête SQL, on peut optimiser les performances en préparant la requête une fois pour toutes au démarrage, plutôt qu'à chaque utilisation. Cette directive permet de préparer une requête SQL et de lui assigner une étiquette.

Directive DBDriver

Description: | Spécifie un pilote SQL
Syntaxe: | DBDriver nom
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_dbd

Cette directive permet de spécifier un pilote apr_dbd par son nom. Le pilote doit être installé sur votre système (sur la plupart des systèmes, il s'agit d'un objet partagé ou d'une dll). Par exemple, DBDriver mysql va sélectionner le pilote MySQL dans la bibliothèque apr_dbd_mysql.so.


mod_deflate - Serveur Apache HTTP Version 2.4

Module Apache mod_deflate

Description: | Comprime le contenu avant de le servir au client
Statut: | Extension
Identificateur de Module: | deflate_module
Fichier Source: | mod_deflate.c

Sommaire

Le module mod_deflate implémente le filtre de sortie DEFLATE qui permet de comprimer la sortie de votre serveur avant de l'envoyer au client sur le réseau.

Traitement des bugs

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

Voir aussi

  • Les filtres

Codages supportés

Le seul codage supporté est gzip afin d'assurer une complète compatibilité avec les anciens navigateurs. Le codage deflate n'est donc pas supporté ; voir à ce sujet la documentation de zlib pour une explication détaillée.

Exemples de configurations

Compression et TLS

Certaines applications web sont vulnérables aux attaques visant le vol d'information lorsqu'une connexion TLS transmet des données compressées par deflate. Pour plus de détails, étudiez les attaques de la famille "BREACH".

Voici une configuration simple qui comprime les contenus à base de texte courants.

Ne comprime que certains types de documents

AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript

Activation de la compression

Compression et TLS

Certaines applications web sont vulnérables aux attaques pour vol d'information lorsque la connexion TLS transmet des données compressées par deflate. Pour plus d'informations, voir en détails la famille d'attaques de type "BREACH".

Compression de la sortie

La compression est implémentée par le filtre DEFLATE. La directive suivante active la compression des documents dans le conteneur où elle est placée :

SetOutputFilter DEFLATE
SetEnvIfNoCase Request_URI "\.(?:gif|jpe?g|png)$" no-gzip

Si vous voulez limiter la compression à certains types MIME particuliers, vous pouvez utiliser la directive AddOutputFilterByType. Voici un exemple où la compression n'est activée que pour les fichiers html de la documentation d'Apache :

<Directory "/your-server-root/manual">
    AddOutputFilterByType DEFLATE text/html
</Directory>

Note

Le filtre DEFLATE est toujours inséré après les filtres RESOURCE comme PHP ou SSI. Il n'affecte jamais les sous-requêtes internes.

Note

La variable d'environnement force-gzip, définie à l'aide de la directive SetEnv, permet d'ignorer la configuration de votre navigateur quant aux codages acceptés, et d'envoyer sans condition une sortie comprimée.

Décompression de la sortie

Le module mod_deflate fournit aussi un filtre permettant de décomprimer un corps de réponse comprimé par gzip. Pour activer cette fonctionnalité, vous devez insérer le filtre INFLATE dans la chaîne de filtrage en sortie via la directive SetOutputFilter ou AddOutputFilter, comme dans l'exemple suivant :

<Location "/dav-area">
    ProxyPass "http://example.com/"
    SetOutputFilter INFLATE
</Location>

Dans cet exemple, les sorties comprimées par gzip en provenance de example.com seront décomprimées afin de pouvoir être éventuellement traitées par d'autres filtres.

Décompression de l'entrée

Le module mod_deflate fournit également un filtre permettant de décomprimer un corps de requête comprimé par gzip. Pour activer cette fonctionnalité, vous devez insérer le filtre DEFLATE dans la chaîne de filtrage en entrée via la directive SetInputFilter ou AddInputFilter, comme dans l'exemple suivant :

<Location "/dav-area">
    SetInputFilter DEFLATE
</Location>

Désormais, si une requête contient un en-tête Content-Encoding: gzip, son corps sera automatiquement décomprimé. Peu de navigateurs sont actuellement en mesure de comprimer les corps de requêtes. Cependant, certaines applications spécialisées supportent les requêtes comprimées, comme par exemple certains clients WebDAV.

Note à propos de l'en-tête Content-Length

Si vous évaluez vous-même la taille du corps de requête, ne faites pas confiance à l'en-tête Content-Length! L'en-tête Content-Length indique la longueur des données en provenance du client, et non la quantité d'octets que représente le flux de données décompressé.

Prise en compte des serveurs mandataires

Le module mod_deflate envoie un en-tête de réponse HTTP Vary: Accept-Encoding pour avertir les mandataires qu'une réponse enregistrée dans le cache ne doit être envoyée qu'aux clients qui ont envoyé l'en-tête de requête Accept-Encoding approprié. Ceci permet d'éviter l'envoi d'un contenu comprimé à un client qui ne sera pas en mesure de l'interpréter.

Si vous avez défini des exclusions spécifiques dépendant, par exemple, de l'en-tête User-Agent, vous devez ajouter manuellement des données à l'en-tête Vary afin d'informer les mandataires des restrictions supplémentaires. Par exemple, dans la configuration classique où l'addition du filtre DEFLATE dépend du contenu de l'en-tête User-Agent, vous devez spécifier :

Header append Vary User-Agent

Si votre décision de comprimer le contenu dépend d'autres informations que celles contenues dans les en-têtes de la requête (par exemple la version HTTP), vous devez attribuer à l'en-tête Vary la valeur *, ce qui permet d'empêcher les mandataires compatibles de tout mettre en cache.

Exemple

Header set Vary *

Servir du contenu précompressé

Comme mod_deflate recompresse le contenu demandé à chaque requête, il est possible de gagner en performances en précompressant ce contenu, et en forçant mod_deflate à servir ce contenu précompressé sans avoir à le recompresser à chaque requête. Pour ce faire, utilisez une configuration du style :

<IfModule mod_headers.c>
    # Servir des fichiers CSS compressés avec gzip, s'ils existent, et
    # si le client accepte gzip.
    RewriteCond "%{HTTP:Accept-encoding}" "gzip"
    RewriteCond "%{REQUEST_FILENAME}\.gz" "-s"
    RewriteRule "^(.*)\.css"              "$1\.css\.gz" [QSA]

    # Servir des fichiers JS compressés avec gzip, s'ils existent, et
    # si le client accepte gzip.
    RewriteCond "%{HTTP:Accept-encoding}" "gzip"
    RewriteCond "%{REQUEST_FILENAME}\.gz" "-s"
    RewriteRule "^(.*)\.js"               "$1\.js\.gz" [QSA]

    # Servir des types de contenus corrects, et empêcher mod_deflate
    # d'effectuer un double gzip.
    RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1]
    RewriteRule "\.js\.gz$"  "-" [T=text/javascript,E=no-gzip:1]

    <FilesMatch "(\.js\.gz|\.css\.gz)$">
      # Servir le type de codage correct.
      Header append Content-Encoding gzip

      # Force les mandataires à mettre en cache séparément les fichiers
      # css/js gzippés & non gzippés.
      Header append Vary Accept-Encoding
    </FilesMatch>
</IfModule>

Directive DeflateBufferSize

Description: | Taille du fragment que zlib devra comprimer en une seule fois
Syntaxe: | DeflateBufferSize valeur
Défaut: | DeflateBufferSize 8096
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_deflate

La directive DeflateBufferSize permet de spécifier la taille en octets du fragment que zlib devra comprimer en une seule fois. Si la taille de la réponse compressée est supérieure à celle spécifiée par cette directive, httpd passera à un mode d'encodage fragmenté (l'en-tête HTTP Transfer-Encoding prend la valeur Chunked), ceci ayant comme effet de bord de ne définir aucun en-tête HTTP Content-Length. Il est important de connaître ce comportement, particulièrement lorsque httpd travaille derrière des mandataires inverses avec mise en cache, ou lorsque httpd est configuré pour utiliser mod_cache et mod_cache_disk car les réponses HTTP sans en-tête Content-Length peuvent ne pas être mises en cache.

Directive DeflateCompressionLevel

Description: | Le niveau de compression que nous appliquons à la sortie
Syntaxe: | DeflateCompressionLevel valeur
Défaut: | La valeur par défaut de zlib
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_deflate

La directive DeflateCompressionLevel permet de spécifier le niveau de compression à utiliser ; plus grande est la valeur, meilleure sera la compression, mais plus grand sera aussi le temps CPU nécessaire pour effectuer le traitement.

La valeur doit être comprise entre 1 (compression minimale) et 9 (compression maximale).

Directive DeflateFilterNote

Description: | Enregistre le taux de compression sous la forme d'une note à des fins de journalisation
Syntaxe: | DeflateFilterNote [type] nom de la note
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_deflate

La directive DeflateFilterNote permet de spécifier qu'une note à propos du taux de compression doit être attachée à la requête. Le nom de la note est passé sous la forme d'un argument de la directive. Vous pouvez utiliser cette note à des fins statistiques en enregistrant sa valeur dans votre journal des accès.

Exemple

      DeflateFilterNote ratio

      LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
      CustomLog "logs/deflate_log" deflate

Pour extraire des informations plus précises de vos journaux, vous pouvez utiliser l'argument type pour spécifier le type de données de la note enregistrée dans le journal. type peut prendre une des valeurs suivantes :

Input
Enregistre dans la note la taille en octets du flux en entrée du filtre.
Output
Enregistre dans la note la taille en octets du flux en sortie du filtre.
Ratio
Enregistre le taux de compression (sortie/entrée * 100) dans la note. Il s'agit de la valeur par défaut si l'argument type est omis.

Vous pouvez donc configurer votre journalisation de la manière suivante :

Journalisation détaillée

DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio ratio

LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
CustomLog "logs/deflate_log" deflate

Voir aussi

  • mod_log_config

Directive DeflateInflateLimitRequestBody

Description: | Taille maximale des corps de requête décompressés
Syntaxe: | DeflateInflateLimitRequestBodyvalue
Défaut: | Aucune limite, mais LimitRequestBody s'applique après la compression
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_deflate
Compatibilité: | Disponible à partir de la version 2.4.10 du serveur HTTP Apache

La directive DeflateInflateLimitRequestBody permet de spécifier la taille maximale d'un corps de requête décompressé. Si elle n'est pas définie, c'est la valeur de la directive LimitRequestBody qui s'applique au corps de requête décompressé.

Directive DeflateInflateRatioBurst

Description: | Nombre maximal de fois que le ratio de décompression d'un corps de requête peut être dépassé
Syntaxe: | DeflateInflateRatioBurst value
Défaut: | 3
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_deflate
Compatibilité: | Disponible à partir de la version 2.4.10 du serveur HTTP Apache

La directive DeflateInflateRatioBurst permet de spécifier le nombre maximal de fois que la valeur de la directive DeflateInflateRatioLimit peut être dépassé avant l'arrêt du traitement de la requête.

Directive DeflateInflateRatioLimit

Description: | Ratio de décompression maximum pour les corps de requêtes
Syntaxe: | DeflateInflateRatioLimit value
Défaut: | 200
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_deflate
Compatibilité: | Disponible à partir de la version 2.4.10 du serveur HTTP Apache

La directive DeflateInflateRatioLimit permet de définir le ratio maximum entre la taille d'un corps de requête compressé et sa taille décompressée. Ce ratio est vérifié au fur et à mesure de l'arrivée du corps de requête, et s'il est dépassé plus de DeflateInflateRatioBurst fois, le traitement de la requête est interrompu.

Directive DeflateMemLevel

Description: | La quantité de mémoire utilisable par zlib pour la compression
Syntaxe: | DeflateMemLevel valeur
Défaut: | DeflateMemLevel 9
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_deflate

La directive DeflateMemLevel permet de spécifier la quantité de mémoire utilisable par zlib pour la compression (une valeur comprise entre 1 et 9).

Directive DeflateWindowSize

Description: | Taille de la fenêtre de compression zlib
Syntaxe: | DeflateWindowSize valeur
Défaut: | DeflateWindowSize 15
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_deflate

La directive DeflateWindowSize permet de spécifier la fenêtre de compression zlib (une valeur comprise entre 1 et 15). En général, plus grande sera la taille de la fenêtre, plus grand sera le taux de compression auquel on pourra s'attendre.


mod_dialup - Serveur Apache HTTP Version 2.4

Module Apache mod_dialup

Description: | Envoie le contenu statique avec une bande passante limitée définie par les différents standards des anciens modems.
Statut: | Expérimental
Identificateur de Module: | dialup_module
Fichier Source: | mod_dialup.c

Sommaire

Il s'agit d'un module qui envoie le contenu statique avec une bande passante limitée définie par les différents standards des anciens modems. Ainsi, il est possible de naviguer sur votre site avec un modem 56k V.92 en positionnant une configuration de ce type :

<Location "/mysite">
    ModemStandard "V.92"
</Location>

Auparavant, pour faire des modules de limitation de bande passante, il fallait monopoliser un thread, pour chaque client, et insérer des temporisations pour diminuer la bande passante. Grâce à cette nouvelle fonctionnalité, un gestionnaire peut recevoir les réponses à ses callbacks après N millisecondes, et il sera invoqué par le module MPM Event dans un thread différent à la fin du délai indiqué. À partir de ce moment, le gestionnaire peut continuer à envoyer des données au client.

Directive ModemStandard

Description: | Standard de modem à simuler
Syntaxe: | ModemStandard V.21|V.26bis|V.32|V.34|V.92
Contexte: | répertoire
Statut: | Expérimental
Module: | mod_dialup

Cette directive permet de spécifier le standard de modem que vous souhaitez simuler.

<Location "/mysite">
    ModemStandard "V.26bis"
</Location>


mod_dir - Serveur Apache HTTP Version 2.4

Module Apache mod_dir

Description: | Permet la redirection des adresses se terminant par un répertoire sans slash de fin et la mise à disposition des fichiers index de répertoire
Statut: | Base
Identificateur de Module: | dir_module
Fichier Source: | mod_dir.c

Sommaire

L'index d'un répertoire peut provenir de deux sources :

  • Un fichier écrit par l'utilisateur, dont le nom, en général appelé index.html, peut être défini à l'aide de la directive DirectoryIndex fournie par le module mod_dir.
  • Un listing généré par le serveur, par l'intermédiaire du module mod_autoindex.

Les deux fonctions sont bien distinctes, si bien que vous pouvez supprimer (ou remplacer) la génération automatique d'index, si vous le souhaitez.

Une redirection "slash de fin" est effectuée lorsque le serveur reçoit une requête pour une URL du style http://nom-serveur/foo/nom-rep où nom-rep est le nom d'un répertoire. Comme les répertoires nécessitent un slash de fin, mod_dir effectue une redirection vers http://nom-serveur/foo/nom-rep/.

Directive DirectoryCheckHandler

Description: | Définit la réponse de ce module lorsqu'un autre gestionnaire est utilisé
Syntaxe: | DirectoryCheckHandler On|Off
Défaut: | DirectoryCheckHandler Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_dir
Compatibilité: | Disponible depuis la version 2.4.8 du serveur HTTP Apache. Les versions antérieures à 2.4 se comportaient implicitement comme si "DirectoryCheckHandler ON" avait été spécifié.

La directive DirectoryCheckHandler permet de faire en sorte que mod_dir recherche un index de répertoire ou ajoute des slashes de fin lorsqu'un autre gestionnaire à été défini pour l'URL considérée. Les gestionnaires peuvent être définis à via des directives telles que SetHandler ou par d'autres modules tels que mod_rewrite au cours des substitutions de niveau répertoire.

Dans les versions antérieures à 2.4, ce module ne modifiait pas son comportement si un autre gestionnaire avait été défini pour l'URL considérée. Ceci permettait de servir des index de répertoires même si une directive SetHandler avait été définie pour un répertoire entier, mais pouvait aussi être à l'origine de conflits avec d'autres modules comme mod_rewrite.

Directive DirectoryIndex

Description: | Liste des fichiers ressources à rechercher lorsque le client envoie une requête pour un répertoire
Syntaxe: | DirectoryIndex disabled | url locale [url locale] ...
Défaut: | DirectoryIndex index.html
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_dir

La directive DirectoryIndex permet de définir une liste de fichiers ressources à rechercher lorsqu'un client envoie une requête pour l'index d'un répertoire, en ajoutant un '/' à la fin du nom de ce dernier. url locale est l'URL (codée avec caractères '%') d'un document du serveur, relative au répertoire faisant l'objet de la requête ; il s'agit en général du nom d'un fichier situé dans le répertoire. Si plusieurs URLs sont fournies, le serveur renverra la première d'entre elles qui correspond à une ressource existante. Si aucune ressource ne correspond à la liste des URLs spécifiées, et si l'option Indexes est définie, le serveur générera son propre listing du répertoire.

Exemple

DirectoryIndex index.html

Avec cette configuration, une requête pour l'URL http://example.com/docs/ renverrait au client la ressource http://example.com/docs/index.html si elle existe, ou provoquerait la génération du listing du répertoire si la ressource n'existe pas.

Notez qu'il n'est pas nécessaire que les documents soient relatifs au répertoire ;

DirectoryIndex index.html index.txt  /cgi-bin/index.pl

provoquerait l'exécution du script CGI /cgi-bin/index.pl si aucun des fichiers index.html ou index.txt n'existe dans le répertoire considéré.

La spécification du seul argument "disabled" empêche mod_dir de rechercher un index. Un argument "disabled" sera interprété de manière littérale si d'autres arguments sont présents avant ou après lui, même s'ils sont eux-mêmes des arguments "disabled".

Note: Positionner plusieurs directives DirectoryIndex au coeur du même context complète la liste des ressources et ne l'écrase pas :

# Exemple A: Positionner index.html en page d'index, puis ajouter index.php.
<Directory "/foo">
    DirectoryIndex index.html
    DirectoryIndex index.php
</Directory>

# Exemple B: La même chose que l'exemple A, mais réalisé au moyen d'une seule directive.
<Directory "/foo">
    DirectoryIndex index.html index.php
</Directory>

# Exemple C: Pour remplacer la liste des ressources, il faut d'abord la vider :
# Ici, seul index.php restera référencé comme ressource d'index.
<Directory "/foo">
    DirectoryIndex index.html
    DirectoryIndex disabled
    DirectoryIndex index.php
</Directory>

Directive DirectoryIndexRedirect

Description: | Définit une redirection externe pour les index de répertoires.
Syntaxe: | DirectoryIndexRedirect on | off | permanent | temp | seeother | 3xx-code
Défaut: | DirectoryIndexRedirect off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_dir
Compatibilité: | Disponible depuis la version 2.3.14

Par défaut, c'est la page définie par la directive DirectoryIndex qui est sélectionnée et renvoyée de manière transparente au client. La directive DirectoryIndexRedirect permet de rediriger le client via une redirection de type 3xx.

Les arguments acceptés sont :

  • on : envoie une redirection 302 vers l'index choisi.
  • off : n'envoie aucune redirection. Il s'agit du comportement historique de mod_dir.
  • permanent : envoie une redirection 301 (permanent) vers l'index choisi.
  • temp : ceci est équivalent à on
  • seeother : envoie une redirection 303 (également appelée "See Other") vers l'index choisi.
  • 3xx-code : envoie une redirection accompagnée du code 3xx choisi.

Exemple

DirectoryIndexRedirect on

Une requête pour http://example.com/docs/ se solderait par une redirection temporaire vers http://example.com/docs/index.html si cette ressource existe.

Directive DirectorySlash

Description: | Activation/Désactivation de la redirection "slash de fin"
Syntaxe: | DirectorySlash On|Off
Défaut: | DirectorySlash On
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_dir

La directive DirectorySlash permet de déterminer si mod_dir doit corriger ou non les URLs pointant vers un répertoire.

En général, si un utilisateur envoie une requête pour une ressource sans slash de fin, cette ressource représentant un répertoire, mod_dir le redirige vers la même ressource, mais en ajoutant un slash de fin, et ceci pour plusieurs bonnes raisons :

  • La requête de l'utilisateur contiendra finalement l'URL canonique de la ressource
  • mod_autoindex fonctionnera correctement. Comme il n'indique pas le chemin dans le lien, le chemin de l'URL serait incorrect.
  • La directive DirectoryIndex n'est évaluée que pour les répertoires se terminant par un slash.
  • Les références à des URLs relatives dans les pages html fonctionneront alors correctement.

Si vous ne souhaitez pas voir ces effets, et si les raisons évoquées ci-dessus ne s'appliquent pas à vous, vous pouvez désactiver la redirection comme indiqué ci-dessous. Gardez cependant à l'esprit que ceci peut avoir des répercutions en matière de sécurité.

# voir l'avertissement de sécurité ci-dessous !
<Location "/some/path">
    DirectorySlash Off
    SetHandler some-handler
</Location>

Avertissement de sécurité

La désactivation de la redirection "slash de fin" peut entraîner la divulgation d'informations. Considérons la situation où mod_autoindex est actif (Options +Indexes), où la directive DirectoryIndex a pour valeur une ressource valide (par exemple index.html), et où aucun gestionnaire particulier n'a été défini pour cette URL. Dans ce cas, une requête avec slash de fin afficherait le contenu du fichier index.html ; par contre, une requête sans slash de fin afficherait un listing du contenu du répertoire.

Notez aussi que certains navigateurs peuvent modifier par erreur des requêtes POST en requêtes GET lors d'une redirection, les données POST étant alors perdues.

Directive FallbackResource

Description: | Définit une URL par défaut pour les requêtes qui ne ciblent aucun fichier
Syntaxe: | FallbackResource disabled | url-locale
Défaut: | disabled - httpd renvoie un code d'erreur 404 (Not Found)
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_dir
Compatibilité: | L'argument disabled est disponible à partir de la version 2.4.4 du serveur HTTP Apache.

Cette directive permet de définir un traitement pour toute URL qui ne correspond à aucune ressource de votre système de fichiers, et qui provoquerait sans cela l'envoi d'un code d'erreur HTTP 404 (Not Found). Par exemple

FallbackResource /not-404.php

fait en sorte que les requêtes ne correspondant à aucun fichier soient traitées par non-404.php, sans affecter les requêtes pour des fichiers existants.

Il est souvent souhaitable qu'un seul fichier ou ressource traite toutes les requêtes à destination d'un répertoire particulier, sauf pour les requêtes qui correspondent à un fichier ou script existant. On y fait souvent référence sous le terme 'contrôleur frontal'.

Dans les versions plus anciennes de httpd, cet effet nécessitait en général mod_rewrite, et l'utilisation des tests conditionnels -f et -d pour vérifier l'existence des fichiers et répertoires. Maintenant, une seule ligne de configuration est nécessaire.

FallbackResource /index.php

Les fichiers existants comme des images, des fichiers css, etc... seront traités normalement.

L'argument disabled permet de désactiver cette fonctionnalité dans le cas où l'héritage d'un répertoire parent n'est pas souhaité.

Pour un URI intermédiaire tel que http://example.com/blog/, cet URI intermédiaire doit être spécifié en tant que url-locale :

<Directory "/web/example.com/htdocs/blog">
    FallbackResource /blog/index.php
</Directory>
<Directory "/web/example.com/htdocs/blog/images">
    FallbackResource disabled
</Directory>


mod_dumpio - Serveur Apache HTTP Version 2.4

Module Apache mod_dumpio

Description: | Enregistre toutes les entrées/sorties dans le journal des erreurs de la manière souhaitée.
Statut: | Extension
Identificateur de Module: | dumpio_module
Fichier Source: | mod_dumpio.c

Sommaire

mod_dumpio permet d'enregistrer toutes les entrées reçues par Apache et/ou toutes les sorties envoyées par ce dernier dans le fichier error.log.

L'enregistrement des données s'effectue juste après le décodage SSL (pour les entrées), et juste avant le codage SSL (pour les sorties). Comme on peut s'y attendre, tout ceci peut représenter un volume important de données, et ne doit être utilisé qu'à des fins de débogage.

Activation du support dumpio

Pour activer le module, ce dernier doit être compilé et chargé par l'intermédiaire de la configuration de votre instance d'Apache. La journalisation peut ensuite être activée ou désactivée séparément pour les entrées et sorties à l'aide des directives ci-dessous. En outre, mod_dumpio doit être configuré à LogLevel trace7 :

LogLevel dumpio:trace7

Directive DumpIOInput

Description: | Enregistre toutes les entrées dans le journal des erreurs
Syntaxe: | DumpIOInput On|Off
Défaut: | DumpIOInput Off
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_dumpio
Compatibilité: | DumpIOInput est disponible depuis la version 2.1.3 d'Apache.

Active la journalisation de toutes les entrées.

Exemple

DumpIOInput On

Directive DumpIOOutput

Description: | Enregistre toutes les sorties dans le journal des erreurs
Syntaxe: | DumpIOOutput On|Off
Défaut: | DumpIOOutput Off
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_dumpio
Compatibilité: | DumpIOOutput est disponible depuis la version 2.1.3 d'Apache.

Active la journalisation de toutes les sorties.

Exemple

DumpIOOutput On


mod_echo - Serveur Apache HTTP Version 2.4

Module Apache mod_echo

Description: | Un simple serveur d'écho pour illustrer les modules de protocole
Statut: | Expérimental
Identificateur de Module: | echo_module
Fichier Source: | mod_echo.c

Sommaire

Ce module est un module de protocole exemple permettant d'en illustrer le concept. Il fournit un simple serveur d'écho. Envoyez lui une phrase par telnet, et il vous la renverra.

Directive ProtocolEcho

Description: | Active ou désactive le serveur d'écho
Syntaxe: | ProtocolEcho On|Off
Défaut: | ProtocolEcho Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Expérimental
Module: | mod_echo

La directive ProtocolEcho permet d'activer ou de désactiver le serveur d'écho.

Exemple

ProtocolEcho On


mod_env - Serveur Apache HTTP Version 2.4

Module Apache mod_env

Description: | Modifie l'environnement transmis aux scripts CGI et aux pages SSI
Statut: | Base
Identificateur de Module: | env_module
Fichier Source: | mod_env.c

Sommaire

Ce module permet de contrôler les variables d'environnement internes utilisées par divers modules du serveur HTTP Apache. Ces variables sont aussi accessibles aux scripts CGI en tant que variables d'environnement système natives, et disponibles dans les pages SSI. Les variables d'environnement peuvent être transmises depuis le shell qui a lancé le processus httpd. Elles peuvent également être définies ou supprimées au cours du processus de configuration.

Traitement des bugs

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

Voir aussi

  • Variables d'environnement
  • SetEnvIf

Directive PassEnv

Description: | Transmet des variables d'environnement depuis le shell
Syntaxe: | PassEnv var-env [var-env] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_env

Cette directive permet de spécifier quelles variables d'environnement système natives doivent être disponibles en tant que variables d'environnement internes pour les modules du serveur HTTP Apache, et propagées vers les scripts CGI et les pages SSI. Leurs valeurs sont issues de l'environnement natif de l'OS associé au shell qui a invoqué le processus httpd.

Exemple

PassEnv LD_LIBRARY_PATH

Directive SetEnv

Description: | Définit des variables d'environnement
Syntaxe: | SetEnv var-env [valeur]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_env

Définit une variable d'environnement interne, cette dernière étant ensuite disponible pour les modules du serveur HTTP Apache et transmise aux scripts CGI et aux pages SSI.

Exemple

SetEnv SPECIAL_PATH /foo/bin

Si l'argument valeur est absent, la variable est définie à la valeur d'une chaîne vide.

Les variables d'environnement internes définies par cette directive le sont après l'exécution de la plupart des directives du traitement initial des requêtes, comme les contrôles d'accès et la mise en correspondance des URIs avec les noms de fichiers. Si la variable d'environnement est sensée intervenir au cours de cette phase initiale du traitement, par exemple pour la directive RewriteRule, vous devez plutôt utiliser la directive SetEnvIf pour définir cette variable.

Voir aussi

  • Variables d'environnement

Directive UnsetEnv

Description: | Supprime des variables de l'environnement
Syntaxe: | UnsetEnv var-env [var-env] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_env

Supprime une ou plusieurs variables d'environnement internes parmi celles qui sont transmises aux scripts CGI et aux pages SSI.

Exemple

UnsetEnv LD_LIBRARY_PATH


mod_example_hooks - Serveur Apache HTTP Version 2.4

Module Apache mod_example_hooks

Description: | Illustration de l'API des modules Apache
Statut: | Expérimental
Identificateur de Module: | example_hooks_module
Fichier Source: | mod_example_hooks.c

Sommaire

Certains fichiers situés dans le répertoire modules/examples de l'arborescence de la distribution d'Apache sont fournis à titre d'exemples pour ceux qui souhaitent écrire des modules qui utilisent l'API d'Apache.

Le fichier principal est mod_example_hooks.c, qui constitue une illustration exhaustive des différents mécanismes et syntaxes d'appels. En aucun cas un module additionnel n'aura à inclure des routines pour tous les appels - il n'en nécessitera au contraire qu'un petit nombre !

Le module example_hooks fonctionne réellement. Si vous le chargez dans votre serveur, activez le gestionnaire "example-hooks-handler" dans une section location, et essayez d'accéder à la zone du site web correspondante, vous verrez s'afficher certaines sorties que le module example_hooks produit au cours des différents appels.

Compilation du module example_hooks

Pour inclure le module example_hooks dans votre serveur, effectuez les étapes suivantes :

  1. Exécutez configure avec l'option --enable-example-hooks.
  2. Compilez le serveur (exécutez la commande "make").

Pour ajouter votre propre module :

  1. cp modules/examples/mod_example_hooks.c modules/nouveau_module/mod_monexemple.c
  2. Modifiez le fichier.
  3. Créez modules/nouveau_module/config.m4.
    1. Ajoutez APACHE_MODPATH_INIT(nouveau_module).
    2. Copiez la ligne APACHE_MODULE contenant "example_hooks" depuis modules/examples/config.m4.
    3. Remplacez le premier argument "example-hooks" par monexemple.
    4. Remplacez le second argument par une brève description de votre module. Cette description sera utilisée par la commande configure --help.
    5. Si la compilation de votre module nécessite des drapeaux de compilation C, des drapeaux d'édition de liens, ou de bibliothèques supplémentaires, ajoutez les respectivement à CFLAGS, LDFLAGS et LIBS. Reportez-vous aux fichiers config.m4 des répertoires des autres modules pour plus d'exemples.
    6. Ajoutez APACHE_MODPATH_FINISH.
  4. Créez le fichier module/nouveau_module/Makefile.in. Si la compilation de votre module ne nécessite pas d'instructions particulières, ce fichier ne doit contenir que la ligne include $(top_srcdir)/build/special.mk.
  5. Exécutez ./buildconf à la racine du répertoire.
  6. Compilez le serveur après avoir exécuté la commande configure avec l'option --enable-monexemple.

Utilisation du module mod_example_hooks

Pour activer le module example_hooks, ajoutez à votre fichier httpd.conf un bloc du style :

<Location "/example-hooks-info">
   SetHandler example-hooks-handler
</Location>

Vous pouvez aussi ajouter ce qui suit dans un fichier .htaccess, puis accéder au fichier "test.example" à partir du répertoire correspondant :

AddHandler example-hooks-handler ".example"

Après avoir rechargé la configuration ou redémarré votre serveur, vous devriez pouvoir accéder à ce fichier et voir s'afficher ce qui a été décrit plus haut.

Directive Example

Description: | Directive de démonstration pour illustrer l'API des modules Apache
Syntaxe: | Example
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Expérimental
Module: | mod_example_hooks

La directive Example n'a pour fonction que de définir un drapeau de démonstration que le gestionnaire de contenu du module example_hooks va afficher. Elle ne possède aucun argument. Si vous naviguez vers une URL à laquelle le gestionnaire de contenu example_hooks s'applique, vous verrez s'afficher les routines du module, ainsi que l'ordre dans lequel elles ont été appelées pour servir le document demandé. On peut observer l'effet de cette directive dans la phrase "Example directive declared here: YES/NO".


mod_expires - Serveur Apache HTTP Version 2.4

Module Apache mod_expires

Description: | Génération des en-têtes HTTP Expires et Cache-Control en fonction de critères spécifiés par l'utilisateur
Statut: | Extension
Identificateur de Module: | expires_module
Fichier Source: | mod_expires.c

Sommaire

Ce module permet de contrôler la définition de l'en-tête HTTP Expires et la directive max-age de l'en-tête HTTP Cache-Control dans les réponses du serveur. La date d'expiration peut être définie soit par rapport à la date de dernière modification du fichier source, soit par rapport à l'heure d'accès du client.

Ces en-têtes HTTP permettent d'informer le client quant à la validité et à la persistence du document. S'il est présent dans le cache, et tant qu'il n'est pas arrivé à expiration, le document sera servi à partir de ce dernier, plutôt qu'à partir du document source. Après expiration, la copie du document dans le cache sera considérée comme "expirée" et donc invalide, et une nouvelle copie devra être obtenue à partir du document source.

Pour modifier les directives de contrôle du cache autres que max-age (voir la RFC 2616 section 14.9), vous pouvez utiliser la directive Header.

Lorsque l'en-tête Expires est déjà présent dans la réponse générée par le serveur, par exemple s'il a été créé par un script CGI ou un serveur original via un serveur mandataire, ce module n'ajoute aucun en-tête Expires ou Cache-Control.

Autre syntaxe de définition de l'intervalle

Pour une syntaxe plus lisible, on peut aussi utiliser les directives ExpiresDefault et ExpiresByType comme suit :

ExpiresDefault "base  [plus num type] [num type] ..."
ExpiresByType type/encoding "base  [plus num type] [num type] ..."

où base peut être :

  • access
  • now (équivalent à 'access')
  • modification

Le mot-clé plus est optionnel. num doit correspondre à une valeur entière [compatible avec atoi()], et type peut être choisi parmi :

  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds

Par exemple, pour faire expirer par défaut les documents 1 mois après leur accès, on peut utiliser une des directives suivantes :

ExpiresDefault "access plus 1 month"
ExpiresDefault "access plus 4 weeks"
ExpiresDefault "access plus 30 days"

La date d'expiration peut être définie plus précisément en ajoutant plusieurs clauses 'num type' :

ExpiresByType text/html "access plus 1 month 15 days 2 hours"
ExpiresByType image/gif "modification plus 5 hours 3 minutes"

Notez que si vous utilisez une configuration basée sur la date de modification, l'en-tête Expires ne sera pas ajouté à un contenu qui ne provient pas directement d'un fichier sur disque ; et ceci tout simplement parce que ce type de contenu ne possède pas de date de modification.

Directive ExpiresActive

Description: | Active la génération d'en-têtes Expires
Syntaxe: | ExpiresActive On|Off
Défaut: | ExpiresActive Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Extension
Module: | mod_expires

Cette directive permet d'activer ou de désactiver la génération des en-têtes Expires et Cache-Control pour les documents concernés ; en d'autres termes, si cette directive se trouve dans un fichier .htaccess, par exemple, elle ne s'applique qu'aux documents générés à partir du répertoire considéré. Si elle est définie à Off, les en-têtes ne seront générés pour aucun document du domaine considéré (sauf surcharge de la configuration à un niveau inférieur, comme un fichier .htaccess qui l'emporterait sur le fichier de configuration du serveur). Si elle est définie à On, les en-têtes seront ajoutés aux documents servis en fonction des critères définis par les directives ExpiresByType et ExpiresDefault (voir plus loin).

Notez que cette directive ne permet pas de garantir qu'un en-tête Expires ou Cache-Control sera généré. Si les critères ne sont pas respectés, aucun en-tête ne sera généré, et la directive produira le même effet que si elle n'avait pas été définie.

Directive ExpiresByType

Description: | Définition de la valeur de l'en-tête Expires en fonction du type MIME
Syntaxe: | ExpiresByType type MIME <code>secondes
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Extension
Module: | mod_expires

Cette directive permet de définir la valeur de l'en-tête Expires et de la directive max-age de l'en-tête Cache-Control générés pour les documents du type MIME spécifié (par exemple, text/html). Le second argument définit le nombre de secondes qui seront ajoutées à un temps de base pour calculer la date d'expiration. Cache-Control: max-age se calcule en soustrayant la date de la requête de la date d'expiration et s'exprime en secondes.

Le champ <code> permet de spécifier quel temps doit être utilisé comme temps de base; M signifie que c'est la date de dernière modification du fichier qui doit être utilisée comme temps de base, alors que A signifie que c'est le moment où le client a accédé au document qui doit être utilisé comme temps de base.

La différence d'effet est subtile. Si on utilise M, toutes les copies existantes du document dans tous les caches expireront au même moment, ce qui peut convenir par exemple pour une notice hebdomadaire qui correspond toujours à la même URL. Si on utilise A, la date d'expiration sera différente pour chaque client, ce qui peut convenir pour des fichiers d'images qui ne changent pas très souvent, et en particulier pour un ensemble de documents en relation qui se réfèrent tous aux mêmes images (ces images sont alors accédées de manière répétitive dans un intervalle de temps assez court).

Exemple :

# active la génération des en-têtes Expires
ExpiresActive On
# les images GIF expirent au bout d'un mois dans le cache du
# client
ExpiresByType image/gif A2592000
# les documents HTML restent valables une semaine après leur date
# de dernière modification
ExpiresByType text/html M604800

Notez que cette directive ne produit d'effet que si ExpiresActive On a été spécifié. Elle l'emporte, mais seulement pour le type MIME spécifié, sur toute date d'expiration définie par la directive ExpiresDefault.

Vous pouvez aussi définir le mode de calcul de la date d'expiration en utilisant une syntaxe alternative, comme décrit plus haut dans ce document.

Directive ExpiresDefault

Description: | Mode de calcul par défaut de la date d'expiration
Syntaxe: | ExpiresDefault <code>secondes
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Extension
Module: | mod_expires

Cette directive permet de définir le mode de calcul par défaut de la date d'expiration pour tous les documents du domaine considéré. Elle peut être annulée pour certains types de documents par la directive ExpiresByType. Voir la description de cette dernière directive pour plus de détails à propos de la syntaxe de l'argument, ainsi que la description de la syntaxe alternative.


mod_ext_filter - Serveur Apache HTTP Version 2.4

Module Apache mod_ext_filter

Description: | Fait traiter le corps de la réponse par un programme externe avant de l'envoyer au client
Statut: | Extension
Identificateur de Module: | ext_filter_module
Fichier Source: | mod_ext_filter.c

Sommaire

mod_ext_filter représente un modèle de programmation simple et bien connu pour les filtres. Avec ce module, tout programme qui lit l'entrée standard stdin et écrit sur la sortie standard stdout (autrement dit une commande filtre de style Unix) peut servir de filtre pour Apache. Ce mécanisme de filtrage est beaucoup plus lent qu'un filtre spécialement écrit pour l'API d'Apache et faisant partie intégrante du processus du serveur Apache, mais il présente les avantages suivants :

  • le modèle de programmation est beaucoup plus simple
  • tout langage de script ou de programmation peut être utilisé, pourvu qu'il permette au programme de lire l'entrée standard et d'écrire sur la sortie standard.
  • on peut utiliser des programmes existants comme filtres Apache sans modification.

Même dans le cas où le niveau de performance est insuffisant pour une utilisation en production, on peut utiliser mod_ext_filter comme prototype d'environnement pour les filtres.

Traitement des bugs

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

Voir aussi

  • Filtres

Exemples

Générer du HTML à partir d'un autre type de contenu

# la directive de mod_ext_filter définissant un filtre
# permettant de mettre des fichiers text/c au format HTML en
# utilisant le programme externe /usr/bin/enscript, le type du
# fichier résultant étant défini à text/html
ExtFilterDefine c-to-html mode=output \
    intype=text/c outtype=text/html \
    cmd="/usr/bin/enscript --color -w html -Ec -o -"

<Directory "/export/home/trawick/apacheinst/htdocs/c">
    # directive de base permettant de traiter la sortie avec le
    # nouveau filtre
    SetOutputFilter c-to-html

    # directive de mod_mime définissant le type des fichiers dont
    # le nom possède l'extension .c à text/c
    AddType text/c .c
</Directory>

Implémentation d'un filtre de codage de contenu

Note : cet exemple avec gzip n'est fourni qu'à titre d'illustration. Veuillez vous reporter à la documentation de mod_deflate pour un exemple d'implémentation plus pratique.

# la directive de mod_ext_filter qui définit le filtre externe
ExtFilterDefine gzip mode=output cmd=/bin/gzip

<Location "/gzipped">

    # directive de base permettant de traiter la sortie avec le
  # filtre gzip
    SetOutputFilter gzip

    # la directive de mod_headers permettant d'ajouter le champ
  # d'en-tête "Content-Encoding: gzip"
    Header set Content-Encoding gzip
</Location>

Ralentissement du serveur

# directive de mod_ext_filter définissant un filtre qui fait
# passer tous les flux en sortie par la commande cat ; cat ne
# modifie rien ; elle ne fait que compliquer le cheminement des
# flux et consommer des ressources supplémentaires
       ExtFilterDefine slowdown mode=output cmd=/bin/cat \
ExtFilterDefine slowdown mode=output cmd=/bin/cat \
    preservescontentlength

<Location "/">
    # directive de base permettant de traiter plusieurs fois la
    # sortie avec le filtre slowdown
    #
    SetOutputFilter slowdown;slowdown;slowdown
</Location>

Utilisation de sed pour remplacer du texte dans la réponse

# directive de mod_ext_filter définissant un filtre qui
# remplace du texte dans la réponse
#
ExtFilterDefine fixtext mode=output intype=text/html \
    cmd="/bin/sed s/verdana/arial/g"

<Location "/">
    # directive de base permettant de traiter la sortie avec le
    # filtre fixtext
    SetOutputFilter fixtext
</Location>

Vous pouvez aussi utiliser mod_substitute pour effectuer le même traitement sans avoir à invoquer un programme externe.

Tracer un autre filtre

# Trace les données lues et écrites par mod_deflate pour un
# client particulier (IP 192.168.1.31) qui a des problèmes de
# compression.
# Ce premier filtre va tracer ce qui entre dans mod_deflate.
ExtFilterDefine tracebefore \
    cmd="/bin/tracefilter.pl /tmp/tracebefore" \
    EnableEnv=trace_this_client

# Ce second filtre va tracer ce qui sort de mod_deflate.
# Notez que sans le paramètre ftype, le type de filtre par
# défaut AP_FTYPE_RESOURCE placerait le filtre *avant*
# mod_deflate dans la chaîne de filtrage. Le fait d'affecter
# à ce paramètre une valeur numérique sensiblement supérieure à
# AP_FTYPE_CONTENT_SET permet de s'assurer que le filtre sera
# placé après mod_deflate.
ExtFilterDefine traceafter \
    cmd="/bin/tracefilter.pl /tmp/traceafter" \
    EnableEnv=trace_this_client ftype=21

<Directory "/usr/local/docs">
    SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
    SetOutputFilter tracebefore;deflate;traceafter
</Directory>

Voici le filtre qui trace les données :

#!/usr/local/bin/perl -w
use strict;

open(SAVE, ">$ARGV[0]")
    or die "can't open $ARGV[0]: $?";

while (<STDIN>) {
    print SAVE $_;
    print $_;
}

close(SAVE);

Directive ExtFilterDefine

Description: | Définit un filtre externe
Syntaxe: | ExtFilterDefine nom_filtre paramètres
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ext_filter

La directive ExtFilterDefine définit les caractéristiques d'un filtre externe, et en particulier le programme à exécuter ainsi que ses arguments.

nom_filtre spécifie le nom du filtre en cours de définition. On peut ensuite utiliser ce nom pour référencer le filtre dans les directives SetOutputFilter. Il doit être unique parmi les noms de tous les filtres enregistrés. Pour le moment, aucune erreur n'est signalée par l'API register-filter, si bien qu'un problème de noms dupliqués ne sera pas porté à la connaissance de l'utilisateur.

Viennent ensuite un ou plusieurs paramètres dans un ordre indéfini, qui permettent de spécifier la commande externe à exécuter et certaines autres caractéristiques. Le seul paramètre obligatoire est cmd=. Voici la liste de ces paramètres :

cmd=ligne de commande
Le mot-clé cmd= spécifie la commande externe à exécuter. Si la ligne de commande comporte des arguments, elle doit être entourée de guillemets (par exemple cmd="/bin/mypgm arg1 arg2"). Les guillemets habituels du shell ne sont pas nécessaires car le programme est lancé directement, sans passer par le shell. Les arguments du programme doivent être séparés par des espaces. Si un argument contient des espaces, ces derniers doivent être échappés par un antislash '\'. Si un argument contient des antislashes '\', ces derniers doivent être eux-mêmes échappés par un antislash '\'. Outre les variables d'environnement CGI standards, les variables DOCUMENT_URI, DOCUMENT_PATH_INFO, et QUERY_STRING_UNESCAPED seront également définies pour le programme.
mode=mode
Utilisez mode=output (valeur par défaut) pour les filtres qui traitent les réponses. Utilisez mode=input pour les filtres qui traitent les requêtes. mode=input est disponible depuis la version 2.1 d'Apache.
intype=type MIME
Ce paramètre spécifie le type de médium Internet (c'est à dire le type MIME) des documents qui doivent être filtrés. Par défaut, tous les documents sont filtrés. Aucun des documents possédant un type MIME autre que celui spécifié par intype= ne sera filtré.
outtype=type MIME
Ce paramètre spécifie le type de médium Internet (c'est à dire le type MIME) des documents filtrés. Il intervient lorsque les opérations de filtrage comprennent une modification du type MIME. Par défaut, le type MIME n'est pas modifié.
PreservesContentLength
Le mot-clé PreservesContentLength indique que le filtre doit conserver la taille du contenu. Ce n'est pas le comportement par défaut, car la plupart des filtres modifient cette taille. Ce mot-clé doit être spécifié si le filtre ne doit pas modifier la taille du contenu.
ftype=type de filtre
Ce paramètre spécifie une valeur numérique représentant le type de filtre sous lequel le filtre doit être enregistré. La valeur par défaut, AP_FTYPE_RESOURCE, convient dans la plupart des situations. Ce paramètre devient nécessaire dès lors que le filtre doit opérer à un autre point de la chaîne de filtrage que les filtres de ressources. Voir les définitions de AP_FTYPE_... dans util_filter.h pour trouver une valeur appropriée.
disableenv=env
Ce paramètre spécifie le nom d'une variable d'environnement qui, si elle est définie, va désactiver le filtre.
enableenv=env
Ce paramètre spécifie le nom d'une variable d'environnement qui doit être définie pour que le filtre ne soit pas désactivé.

Directive ExtFilterOptions

Description: | Configure les options de mod_ext_filter
Syntaxe: | ExtFilterOptions option [option] ...
Défaut: | ExtFilterOptions NoLogStderr
Contexte: | répertoire
Statut: | Extension
Module: | mod_ext_filter

La directive ExtFilterOptions spécifie des options de traitement particulières pour mod_ext_filter. Les arguments option peuvent contenir :

LogStderr | NoLogStderr
Le mot-clé LogStderr indique que les messages envoyés par le programme de filtrage externe sur la sortie d'erreurs standard doivent être enregistrés dans le journal des erreurs d'Apache. NoLogStderr inverse ce comportement.
Onfail=[abort|remove]
Indique la marche à suivre si le programme de filtrage externe ne peut pas démarrer. Avec abort (la valeur par défaut), le traitement de la requête sera abandonné. Avec remove, le filtre est supprimé, et le traitement de la requête se poursuit sans lui.
ExtFilterOptions LogStderr

Les messages envoyés vers la sortie d'erreurs standard du filtre seront enregistrés dans le journal des erreurs d'Apache.


mod_file_cache - Serveur Apache HTTP Version 2.4

Module Apache mod_file_cache

Description: | Mise en cache mémoire d'une liste statique de fichiers
Statut: | Expérimental
Identificateur de Module: | file_cache_module
Fichier Source: | mod_file_cache.c

Sommaire

Ce module doit être utilisé avec précautions. Il est recommandé de lire attentivement ce document, car l'utilisation de mod_file_cache peut facilement conduire à la création d'un site inopérant.

La mise en cache de fichiers souvent demandés mais rarement modifiés est une technique permettant de réduire la charge du serveur. mod_file_cache met en oeuvre deux techniques de mise en cache de fichiers statiques fréquemment demandés. Des directives de configuration vous permettent d'indiquer à mod_file_cache soit d'ouvrir et de charger une image en mémoire d'un fichier avec mmap(), soit de préouvrir un fichier et de maintenir en service le gestionnaire du fichier. Les deux techniques permettent de réduire la charge du serveur lors du traitement des requêtes concernant ces fichiers, en accomplissant une partie du travail nécessaire à la mise à disposition de ces fichiers (en particulier les opérations d'entrées/sorties sur les fichiers) au démarrage du serveur, plutôt qu'au cours de chaque requête.

Note : ces techniques sont inutilisables pour accélérer des programmes CGI ou d'autres fichiers servis par des gestionnaires de contenu spéciaux. Elles ne peuvent être utilisées que pour des fichiers standards, normalement servis par le gestionnaire de contenu de base d'Apache.

Ce module est une extension du module d'Apache 1.3 mod_mmap_staticet s'en inspire fortement .

Utilisation de mod_file_cache

mod_file_cache gère la mise en cache d'une liste de fichiers définie de manière statique via une des directives MMapFile ou CacheFile au niveau de la configuration du serveur principal.

Les deux directives ne sont pas supportées par toutes les plates-formes. Par exemple, Apache pour Windows ne supporte pas actuellement la directive MMapFile, alors que d'autres plates-formes, comme AIX, supportent les deux. Vous recevrez un message d'erreur dans le journal des erreurs du serveur si vous essayez d'utiliser une directive non supportée. Si vous utilisez une directive non supportée, le serveur démarrera, mais les fichiers ne seront pas mis en cache. Sur les plates-formes qui supportent les deux directives, vous devez faire des essais afin de déterminer quelle directive vous convient le mieux.

Directive MMapFile

La directive MMapFile du module mod_file_cache permet de transférer en mémoire une liste statique de fichiers à l'aide de l'appel système mmap(). Cet appel système est disponible sur la plupart des plates-formes de style Unix, mais pas sur toutes. Il existe parfois des limites spécifiques au système quant à la taille et au nombre de fichiers qui peuvent être mmap()és, et l'expérimentation est probablement la méthode la plus simple pour déterminer ces limites.

Ce mmap()age n'est effectué qu'une seul fois au démarrage ou redémarrage du serveur. Ainsi, chaque fois qu'un des fichiers chargés en mémoire est modifié au niveau du système de fichiers, vous devez redémarrer le serveur (voir la documentation sur l'Arrêt et redémarrage). Pour bien insister sur ce point, si des fichiers sont modifiés sur disque, et si vous ne redémarrez pas le serveur, vous allez finir par servir des contenus complètement obsolètes. Vous devez mettre à jour les fichiers en renommant l'ancienne version et en enregistrant la nouvelle sur disque. Pour y parvenir, on peut utiliser des outils comme rdist et mv. La raison pour laquelle ce module ne prend pas en compte les modifications de fichiers réside dans le fait que cette vérification nécessiterait un appel à stat() à chaque accès, et en fin de compte, l'augmentation de la consommation de ressources finirait par aller contre le but initial de réduire les entrées/sorties.

Directive CacheFile

La directive CacheFile du module mod_file_cache permet d'associer un gestionnaire ou descripteur de fichier à chaque fichier énuméré dans la directive de configuration et place ces gestionnaires de fichiers ouverts dans le cache. Lorsqu'un des fichier est demandé, le serveur sélectionne son gestionnaire dans le cache et le transmet à l'API sendfile() (ou TransmitFile() sous Windows).

Cette mise en cache des gestionnaire n'est effectuée qu'une seule fois au démarrage ou redémarrage du système. Ainsi, chaque fois qu'un des fichiers chargés en mémoire est modifié au niveau du système de fichiers, vous devez redémarrer le serveur (voir la documentation sur l'Arrêt et redémarrage). Pour bien insister sur ce point, si des fichiers sont modifiés sur disque, et si vous ne redémarrez pas le serveur, vous allez finir par servir des contenus complètement obsolètes. Vous devez mettre à jour les fichiers en renommant l'ancienne version et en enregistrant la nouvelle sur disque. Pour y parvenir, on peut utiliser des outils comme rdist et mv.

Note

Ne cherchez pas à trouver de directive qui met tous les fichiers d'un répertoire en cache, de manière récursive. Pour y parvenir, vous pouvez vous reporter à la directive Include directive, et considérer cette commande :

find /www/htdocs -type f -print \
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf

Directive CacheFile

Description: | Met en cache une liste de gestionnaires de fichiers au démarrage
Syntaxe: | CacheFile chemin fichier [chemin fichier] ...
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_file_cache

La directive CacheFile permet d'associer des gestionnaires à un ou plusieurs fichiers (séparés par des espaces), et de placer ceux-ci dans le cache au démarrage du serveur. Les gestionnaires des fichiers mis en cache sont automatiquement fermés à l'arrêt du serveur. Lorsqu'un ou plusieurs fichiers ont été modifiés sur disque, le serveur doit être redémarré afin que les modifications soient prises en compte par le cache.

Soyez prudent avec les arguments chemin fichier : ils doivent correspondre exactement au chemin du système de fichier que créent les gestionnaires de traduction URL-vers-nom-fichier d'Apache. On ne peut pas comparer des inodes ou autres identifiants pour mettre en correspondance des chemins à l'aide de liens symboliques (etc...), car là encore, ceci nécessiterait un appel à stat() supplémentaire, ce qui n'est pas acceptable. Il n'est pas garanti que ce module fonctionne avec des noms de fichiers réécrits par mod_alias ou mod_rewrite.

Exemple

CacheFile /usr/local/apache/htdocs/index.html

Directive MMapFile

Description: | Charge au démarrage une liste de fichiers en mémoire
Syntaxe: | MMapFile chemin fichier [chemin fichier] ...
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_file_cache

La directive MMapFile permet de charger un ou plusieurs fichiers (séparés par des espaces) en mémoire au démarrage du serveur. Ceux-ci sont automatiquement déchargés de la mémoire à l'arrêt du serveur. Lorsqu'un ou plusieurs fichiers ont été modifiés sur disque, on doit au minimum envoyer un signal HUP ou USR1 au serveur afin de les remmap()er.

Soyez prudent avec les arguments chemin fichier : ils doivent correspondre exactement au chemin du système de fichier que créent les gestionnaires de traduction URL-vers-nom-fichier d'Apache. On ne peut pas comparer des inodes ou autres identifiants pour mettre en correspondance des chemins à l'aide de liens symboliques (etc...), car là encore, ceci nécessiterait un appel à stat() supplémentaire, ce qui n'est pas acceptable. Il n'est pas garanti que ce module fonctionne avec des noms de fichiers réécrits par mod_alias ou mod_rewrite.

Exemple

MMapFile /usr/local/apache/htdocs/index.html


mod_filter - Serveur Apache HTTP Version 2.4

Module Apache mod_filter

Description: | Module de configuration de filtre intelligent sensible au contexte
Statut: | Base
Identificateur de Module: | filter_module
Fichier Source: | mod_filter.c
Compatibilité: | Versions 2.1 et supérieures

Sommaire

Ce module permet une configuration intelligente et dépendant du contexte des filtres de contenu en sortie. Par exemple, Apache peut être configuré pour faire traiter différents types de contenus par différents filtres, même lorsque le type de contenu n'est pas connu à l'avance (par exemple dans un serveur mandataire).

Le fonctionnement de mod_filter consiste à introduire des branchements dans la chaîne de filtrage. Plutôt que d'insérer directement des filtres dans la chaîne, on insère un sélecteur de filtre qui va effectuer un branchement conditionnel vers un fournisseur de filtre. mod_filter peut utiliser tout filtre de contenu comme fournisseur ; aucune modification des modules de filtrage existants n'est nécessaire (bien qu'il soit tout de même possible de les simplifier).

Filtrage intelligent

Dans le modèle de filtrage traditionnel, les filtres sont insérés sans condition à l'aide de la directive AddOutputFilter et des directives apparentées. Chaque filtre doit ensuite déterminer s'il doit s'exécuter ou non, et les administrateurs du serveur disposent de peu de souplesse pour faire en sorte que la chaîne soit traitée de manière dynamique.

mod_filter, à l'opposé, fournit aux administrateurs du serveur un grand degré de souplesse pour configurer la chaîne de filtrage. Concrètement, la décision d'insérer un filtre peut être prise en fonction d'une expression booléenne complexe. Ceci généralise le fonctionnement relativement souple de la directive AddOutputFilterByType.

Déclarations de filtres, fournisseurs et chaînes

[Cette image illustre le modèle de filtrage traditionnel]
Figure 1: Le modèle de filtrage traditionnel

Dans le modèle traditionnel, les filtres en sortie constituent une simple chaîne s'étendant depuis le générateur de contenu (ou gestionnaire) jusqu'au client. Ce fonctionnement peut convenir s'il permet d'atteindre le but recherché, mais pose problème lorsque cette chaîne doit être configurée dynamiquement en fonction de la sortie du gestionnaire.

[Cette image illustre le modèle de fonctionnement de mod_filter]
Figure 2: Le modèle de fonctionnement de mod_filter

Le fonctionnement de mod_filter consiste à introduire des branchements dans la chaîne de filtrage. Plutôt que d'insérer directement des filtres dans la chaîne, on insère un sélecteur de filtre qui va effectuer un branchement conditionnel vers un fournisseur de filtre. mod_filter peut utiliser tout filtre de contenu comme fournisseur ; aucune modification des modules de filtrage existants n'est nécessaire (bien qu'il soit tout de même possible de les simplifier). Il peut y avoir plusieurs fournisseurs pour un seul filtre, mais un seul fournisseur sera choisi pour chaque requête.

Une chaîne de filtrage peut comporter autant d'instances du sélecteur de filtre que l'on souhaite, chacune d'entre elles pouvant disposer de plusieurs fournisseurs. Un sélecteur de filtre possédant un seul fournisseur dont le choix est inconditionnel constitue un cas particulier : cette situation est équivalente à l'insertion directe du filtre dans la chaîne.

Configuration de la chaîne de filtrage

Trois étapes sont nécessaires pour configurer une chaîne de filtrage avec mod_filter. Voir ci-dessous la description détaillée des directives.

Déclaration des filtres
La directive FilterDeclare permet de déclarer un filtre en lui assignant un nom et un type. Elle n'est obligatoire que si le filtre n'est pas du type par défaut AP_FTYPE_RESOURCE.
Enregistrement des fournisseurs
La directive FilterProvider permet d'associer un fournisseur à un filtre. Le filtre a été éventuellement déclaré à l'aide de la directive FilterDeclare ; si ce n'est pas le cas, FilterProvider va le déclarer implicitement avec le type par défaut AP_FTYPE_RESOURCE. Le fournisseur doit avoir été enregistré à l'aide de ap_register_output_filter par un module quelconque. Le dernier argument de la directive FilterProvider est une expression : le fournisseur s'exécutera pour une requête si et seulement si l'expression est évaluée vraie. L'expression peut évaluer une requête HTTP ou les en-têtes de la réponse, des variables d'environnement, ou le gestionnaire utilisé par cette requête. À la différence des version précédentes, mod_filter supporte désormais les expressions complexes associant des critères multiples au moyen d'une logique AND / OR (&& / ||) et de parenthèses. Pour les détails sur la syntaxe de l'expression, voir la documentation sur ap_expr.
Configuration de la chaîne de filtrage
Les directives ci-dessus permettent d'élaborer les éléments d'une chaîne de filtrage intelligente, mais pas de les configurer en vue de leur exécution. La directive FilterChain élabore une chaîne de filtrage à partir de filtres intelligents déclarés, permettant avec souplesse d'insérer des filtres au début ou à la fin de la chaîne, de supprimer un filtre ou même la chaîne complète.

Filtrage et statut de la réponse

Normalement, mod_filter n'applique les filtres qu'aux réponses possédant un statut HTTP 200 (OK). Pour pouvoir filtrer des documents possédant un autre statut, vous devez définir la variable d'environnement filter-errordocs, les réponses étant alors filtrées sans se préoccuper de leur statut. Pour définir ce comportement de manière plus fine, vous pouvez utiliser des conditions dans la directive FilterProvider.

Mise à jour depuis une configuration du serveur HTTP Apache 2.2

La directive FilterProvider a été modifiée par rapport à httpd 2.2 : les arguments match et dispatch ont été remplacés par l'argument unique expression plus polyvalent. En général, il est possible de convertir une paire match/dispatch vers les deux côtés d'une expression, de la manière suivante :

"dispatch = 'match'"

Les en-têtes de requête et de réponse et les variables d'environnement sont maintenant interprétés selon les syntaxes respectives %{req:foo}, %{resp:foo} et %{env:foo}. Les variables %{HANDLER} et %{CONTENT_TYPE} sont également supportées.

Notez que l'évaluation de l'expression ne supporte plus les comparaisons de sous-chaînes. Ces dernières peuvent être remplacées par des comparaisons d'expressions rationnelles.

Exemples

Inclusions côté serveur (SSI)
Un exemple simple de remplacement de la directive AddOutputFilterByType
FilterDeclare SSI
FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
FilterChain SSI
Inclusions côté serveur (SSI)
Même exemple que ci-dessus, mais envoi vers un gestionnaire (comportement classique des SSI ; les fichiers .shtml sont traités).
FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
FilterChain SSI
Émulation de mod_gzip avec mod_deflate
Insertion du filtre INFLATE seulement si l'en-tête Accept-Encoding a une valeur autre que "gzip". Ce filtre s'exécute avec le type ftype CONTENT_SET.
FilterDeclare gzip CONTENT_SET
FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
FilterChain gzip
Diminution de la résolution d'une image
Supposons que nous voulions réduire la résolution de toutes les images web, et que nous disposions de filtres pour les images GIF, JPEG et PNG.
FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider unpack gif_unpack  "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider unpack png_unpack  "%{CONTENT_TYPE} = 'image/png'"

FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
FilterProtocol downsample "change=yes"

FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider repack gif_pack  "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider repack png_pack  "%{CONTENT_TYPE} = 'image/png'"
<Location "/image-filter">
    FilterChain unpack downsample repack
</Location>

Gestion de protocole

Historiquement, tout filtre doit s'assurer que toute modification qu'il effectue est correctement représentée dans les en-têtes de la réponse HTTP, et qu'il ne s'exécutera pas si cette exécution résultait en une modification interdite. Ceci impose aux auteurs de filtres la corvée de réimplémenter certaines fonctionnalités communes dans chaque filtre :

  • De nombreux filtres modifient les contenus, et de ce fait invalident les balises de ces contenus, leur somme de contrôle, leur condensé (hash) existant, ainsi que leur taille.
  • Les filtres qui nécessitent une réponse entière et non tronquée en entrée, doivent s'assurer qu'il n'ont pas reçu une réponse à une requête partielle.
  • Les filtres qui modifient la sortie d'un autre filtre doivent s'assurer qu'ils ne violent pas la directive d'un en-tête Cache-Control: no-transform éventuel.
  • Les filtres peuvent agir sur des réponses de façon à ce qu'elles ne puissent plus être mises en cache.

mod_filter a pour but de gérer de manière générale ces détails de l'implémentation des filtres, réduisant par là-même la complexité des modules de filtrage de contenu. Le travail permettant d'atteindre ce but est cependant toujours en cours ; la directive FilterProtocol implémente certaines de ces fonctionnalités à des fins de compatibilité ascendante avec les modules d'Apache 2.0. Pour les versions 2.1 et supérieures de httpd, les API ap_register_output_filter_protocol et ap_filter_protocol permettent aux modules de filtrage de définir leurs propres comportements.

Cependant, mod_filter ne doit pas interférer avec un filtre qui gère déjà tous les aspects du protocole. Par défaut (c'est à dire en l'absence de toute directive FilterProtocol), mod_filter ne modifiera donc pas les en-têtes.

Au moment où ces lignes sont écrites, cette fonctionnalité a été très peu testée, car les modules d'usage courant ont été conçus pour fonctionner avec httpd 2.0. Les modules qui l'utilisent devront donc l'expérimenter avec précautions.

Directive AddOutputFilterByType

Description: | assigne un filtre en sortie pour un type de média particulier
Syntaxe: | AddOutputFilterByType filtre[;filtre...] type_de_média [type_de_média] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_filter
Compatibilité: | Présentait de sévères limitations avant d'être déplacé dans mod_filter dans la version 2.3.7

Cette directive active un filtre en sortie particulier pour une requête en fonction du type de média de la réponse.

L'exemple suivant active le filtre DEFLATE qui est fourni par le module mod_deflate. Il va compresser toute sortie dont le type MIME est text/html ou text/plain avant de l'envoyer au client.

AddOutputFilterByType DEFLATE text/html text/plain

Si vous voulez assigner plusieurs filtres au contenu, leurs noms doivent être séparés par des points-virgules. On peut aussi utiliser une directive AddOutputFilterByType pour chacun des filtres à assigner.

La configuration ci-dessous impose le traitement de toute sortie de script dont le type MIME est text/html en premier lieu par le filtre INCLUDES, puis par le filtre DEFLATE.

<Location "/cgi-bin/">
    Options Includes
    AddOutputFilterByType INCLUDES;DEFLATE text/html
</Location>

Voir aussi

  • AddOutputFilter
  • SetOutputFilter
  • Les filtres

Directive FilterChain

Description: | Configure la chaîne de filtrage
Syntaxe: | FilterChain [+=-@!]nom_filtre ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet de configurer une chaîne de filtrage composée de filtres déclarés. FilterChain accepte un nombre illimité d'arguments, chacun d'entre eux étant précédé d'un caractère de contrôle unique qui détermine l'action à entreprendre :

+nom filtre
Ajoutenom filtre à la fin de la chaîne de filtrage
@nom filtre
Ajoute nom filtre au début de la chaîne de filtrage
-nom filtre
Supprime nom filtre de la chaîne de filtrage
=nom filtre
Supprime tous les filtres de la chaîne de filtrage existante et les remplace par nom filtre
!
Supprime tous les filtres de la chaîne de filtrage existante
nom filtre
Équivalent à +nom filtre

Directive FilterDeclare

Description: | Déclare un filtre intelligent
Syntaxe: | FilterDeclare nom_filtre [type]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet de déclarer un filtre en sortie associé à un en-tête ou une variable d'environnement qui déterminera les conditions de son exécution. Le premier argument est le nom du filtre destiné à être utilisé dans les directives FilterProvider, FilterChain et FilterProtocol.

Le dernier argument (optionnel) est le type du filtre, et peut prendre les valeurs de ap_filter_type, à savoir RESOURCE (valeur par défaut), CONTENT_SET, PROTOCOL, TRANSCODE, CONNECTION ou NETWORK.

Directive FilterProtocol

Description: | Vérifie le respect du protocole HTTP
Syntaxe: | FilterProtocol nom_filtre [nom_fournisseur] drapeaux_protocole
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet à mod_filter de s'assurer qu'un filtre ne s'exécutera pas s'il ne doit pas le faire, et que les en-têtes de la réponse HTTP sont définis correctement en tenant compte des effets du filtre.

Cette directive se présente sous deux formes. Avec trois arguments, elle s'applique de manière spécifique à un nom filtre et un nom fournisseur pour ce filtre. Avec deux arguments, elle s'applique à un nom filtre pour tout fournisseur qu'il actionne.

Les drapeaux spécifiés sont fusionnés avec les drapeaux que les fournisseurs sous-jacents ont éventuellement enregistrés avec mod_filter. Par exemple, un filtre peut avoir spécifié en interne un drapeau équivalent à change=yes, mais une configuration particulière du module peut le surcharger en spécifiant change=no.

drapeaux_protocole peut contenir un ou plusieurs drapeaux parmi les suivants :

change=yes|no
Indique si le filtre doit modifier le contenu, y compris éventuellement sa taille
change=1:1
Le filtre modifie le contenu, mais pas sa taille
byteranges=no
Le filtre ne peut pas traiter de réponses à des sous-requêtes et nécessite des réponses complètes en entrée
proxy=no
Le filtre ne doit pas s'exécuter dans un contexte de mandataire
proxy=transform
Le filtre transforme la réponse de manière incompatible avec l'en-tête HTTP Cache-Control: no-transform
cache=no
Le filtre fait en sorte que la sortie ne puisse pas être mise en cache (par exemple en introduisant des modifications de contenu aléatoires)

Directive FilterProvider

Description: | Enregistre un filtre de contenu
Syntaxe: | FilterProvider nom_filtre nom_fournisseur expression
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_filter

Cette directive permet d'associer un fournisseur au filtre intelligent. Le fournisseur sera invoqué si et seulement si l'expression est évaluée vraie lorsque le sélecteur de filtre est appelé pour la première fois.

nom fournisseur doit avoir été enregistré au cours du chargement d'un module à l'aide de ap_register_output_filter.

expression est une expression ap_expr.

Voir aussi

  • Les expressions dans le serveur HTTP Apache, pour une référence complète et d'autres exemples.
  • mod_include

Directive FilterTrace

Description: | Obtention d'informations de débogage/diagnostique en provenance de mod_filter
Syntaxe: | FilterTrace nom_filtre niveau
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_filter

Cette directive permet d'obtenir des informations de débogage en provenance de mod_filter. Elle est conçue pour aider à tester et déboguer les fournisseurs (ou modules de filtrage) ; elle peut aussi apporter une aide à l'utilisation de mod_filter lui-même.

La sortie de débogage dépend de la définition d'argument level :

0 (valeur par défaut)
Aucune information de débogage n'est générée.
1
mod_filter va enregistrer les ensembles de conteneurs de données (buckets and brigades) qui traversent le filtre dans le journal des erreurs, avant que le fournisseur ne les traite. Ces informations sont similaires à celles générées par mod_diagnostics.
2 (pas encore implémenté)
Ce niveau permettra d'enregistrer l'ensemble des données qui traversent le filtre dans un fichier temporaire avant de les envoyer au fournisseur. Pour un débogage mono-utilisateur seulement ; l'enregistrement des données concernant plusieurs requêtes simultannées ne sera pas supporté.


mod_headers - Serveur Apache HTTP Version 2.4

Module Apache mod_headers

Description: | Personnalisation des en-têtes de requêtes et de réponses HTTP
Statut: | Extension
Identificateur de Module: | headers_module
Fichier Source: | mod_headers.c

Sommaire

Ce module fournit des directives permettant de contrôler et modifier les en-têtes de requêtes et de réponses HTTP. Les en-têtes peuvent être fusionnés, remplacés ou supprimés.

Chronologie du traitement

Les directives fournies par mod_headers peuvent s'insérer presque partout dans la configuration du serveur, et on peut limiter leur portée en les plaçant dans des sections de configuration.

La chronologie du traitement est importante et est affectée par l'ordre d'apparition des directives dans le fichier de configuration et par leur placement dans les sections de configuration. Ainsi, ces deux directives ont un effet différent si leur ordre est inversé :

RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID

Dans cet ordre, l'en-tête MirrorID n'est pas défini. Si l'ordre des directives était inversé, l'en-tête MirrorID serait défini à "mirror 12".

Traitement précoce et traitement tardif

mod_headers peut agir soir précocement, soit tardivement au niveau de la requête. Le mode normal est le mode tardif, lorsque les en-têtes de requête sont définis, immédiatement avant l'exécution du générateur de contenu, et pour les en-têtes de réponse, juste au moment où la réponse est envoyée sur le réseau. Utilisez toujours le mode tardif sur un serveur en production.

Le mode précoce a été conçu à des fins d'aide aux tests et au débogage pour les développeurs. Les directives définies en utilisant le mot-clé early sont censées agir au tout début du traitement de la requête. Cela signifie que l'on peut les utiliser pour simuler différentes requêtes et définir des situations de test, tout en gardant à l'esprit que les en-têtes peuvent être modifiés à tout moment par d'autres modules avant que le réponse ne soit générée.

Comme les directives précoces sont traitées avant que le chemin de la requête ne soit parcouru, les en-têtes précoces ne peuvent être définis que dans un contexte de serveur principal ou de serveur virtuel. Les directives précoces ne peuvent pas dépendre d'un chemin de requête, si bien qu'elles échoueront dans des contextes tels que <Directory> ou <Location>.

Exemples

  1. Copie tous les en-têtes de requête qui commencent par "TS" vers les en-têtes de la réponse :
    Header echo ^TS
  2. Ajoute à la réponse un en-tête, mon-en-tête, qui contient un horodatage permettant de déterminer le moment où la requête a été reçue, et le temps qui s'est écoulé jusqu'à ce que la requête ait commencé à être servie. Cet en-tête peut être utilisé par le client pour estimer la charge du serveur ou isoler les goulets d'étranglement entre le client et le serveur.
    Header set mon-en-tête "%D %t"

    le résultat est l'ajout à la réponse d'un en-tête du type :

    mon-en-tête: D=3775428 t=991424704447256

  3. Dit Bonjour à Joe

    Header set mon-en-tête "Bonjour Joe. Il a fallu %D microsecondes \
    à Apache pour servir cette requête."

    le résultat est l'ajout à la réponse d'un en-tête du type :

        Header set MyHeader "Bonjour Joe. Il a fallu D=3775428 microsecondes à Apache
          pour servir cette requête."
  4. Ajoute l'en-tête mon-en-tête à la réponse si et seulement si l'en-tête mon-en-tête-requête est présent dans la requête. Ceci peut s'avérer utile pour générer des en-têtes de réponse "à la tête du client". Notez que cet exemple nécessite les services du module mod_setenvif.
    SetEnvIf MyRequestHeader myvalue HAVE_MyRequestHeader
Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader

    Si l'en-tête mon-en-tête-requête: mavaleur est présent dans la requête HTTP, la réponse contiendra un en-tête du type :

    mon-en-tête: D=3775428 t=991424704447256 montexte

  5. Permet à DAV de fonctionner avec Apache sur SSL (voir la description du problème) en remplaçant https: par http: dans l'en-tête Destination :
    RequestHeader edit Destination ^https: http: early
  6. Définit la valeur d'un même en-tête sous de multiples conditions non exclusives, mais ne duplique pas une valeur déjà définie dans l'en-tête qui en résulte. Si toutes les conditions suivantes sont satisfaites pour une requête (en d'autres termes, si les trois variables d'environnement CGI, NO_CACHE et NO_STORE existent pour la requête) :
    Header merge Cache-Control no-cache env=CGI
Header merge Cache-Control no-cache env=NO_CACHE
Header merge Cache-Control no-store env=NO_STORE

    alors, la réponse contiendra l'en-tête suivant :

    Cache-Control: no-cache, no-store

    Si append avait été utilisé à la place de merge, la réponse aurait contenu l'en-tête suivant :

    Cache-Control: no-cache, no-cache, no-store

  7. Définit un cookie de test si et seulement si le client n'envoie pas de cookie
    Header set Set-Cookie testcookie "expr=-z %{req:Cookie}"
  8. Ajoute un en-tête de mise en cache pour les réponses avec un code d'état HTTP de 200
    Header append Cache-Control s-maxage=600 "expr=%{REQUEST_STATUS} == 200"

Directive Header

Description: | Configure les en-têtes d'une réponse HTTP
Syntaxe: | Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note en-tête [[expr=]valeur [remplacement] [early|env=[!]variable|expr=expression]]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_headers
Compatibilité: | SetIfEmpty est disponible depuis la version 2.4.7 du serveur HTTP Apache ; le paramètre expr=valeur a été introduit avec la version 2.4.10

Cette directive permet de remplacer, fusionner, ou supprimer des en-têtes de réponse HTTP. L'en-tête est modifié juste après que le gestionnaire de contenu et les filtres en sortie ne s'exécutent, ce qui permet la modification des en-têtes sortants.

L'argument optionnel condition permet de déterminer sur quelle table interne d'en-têtes de réponses cette directive va opérer. En dépit du nom, la valeur par défaut de onsuccess ne limite pas une action aux réponses avec un code d'état de 2xx. Les en-têtes définis sous cette condition sont encore utilisés quand par exemple une requête est mandatée ou générée par un programme CGI avec succès, et ceci même dans le cas où ils ont généré un code d'échec.

Lorsque votre action est une fonction agissant sur un en-tête existant, vous pourrez être amené à spécifier une condition always, en fonction de la table interne dans laquelle l'en-tête original a été défini. La table qui correspond à always est utilisée pour les réponses d'erreur générées localement ainsi que pour les réponses qui ont abouti. Notez aussi que la répétition de cette directive avec les deux conditions peut être pertinente dans certains scénarios, car always n'englobe pas onsuccess en ce qui concerne les en-têtes existants :

  • Vous ajoutez un en-tête à une réponse générée localement et échouée (non-2xx), une redirection par exemple, et dans ce cas, seule la table correspondant à always est utilisée dans la réponse définitive.
  • Vous modifiez ou supprimez un en-tête généré par un script CGI, et dans ce cas, les scripts CGI sont dans la table correspondant à always et non dans la table par défaut.
  • Vous modifiez ou supprimez un en-tête généré par tel ou tel composant du serveur, mais cet en-tête n'est pas trouvé par la condition par défaut onsuccess.

Outre le paramètre condition décrit ci-dessus, vous pouvez limiter une action en fonction de codes d'état HTTP, par exemple pour les requêtes mandatées ou générées par un programme CGI. Voir l'exemple qui utilise %{REQUEST_STATUS} dans la section ci-dessus.

L'action que cette directive provoque est déterminée par le premier argument (ou par le second argument si une condition est spécifiée). Il peut prendre une des valeurs suivantes :

add
L'en-tête est ajouté au jeu d'en-têtes préexistant, même s'il existe déjà. Ceci peut conduire à la présence de deux (ou plusieurs) en-têtes possèdant le même nom et donc induire des conséquences imprévues ; en général, il est préférable d'utiliser set, append ou merge.
append
La valeur d'en-tête est ajoutée à tout en-tête existant de même nom. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête.
echo
Les en-têtes de la requête possédant le nom spécifié sont recopiés vers les en-têtes de la réponse. en-tête peut être une expression rationnelle, et valeur ne doit pas être présent.
edit
edit*
Si l'en-tête existe, sa valeur est modifiée en fonction d'une expression rationnelle de type recherche/remplacement. L'argument valeur est une expression rationnelle, et l'argument remplacement une chaîne de caractères de remplacement qui peut contenir des références arrières ou des spécificateurs de format. La forme edit n'effectuera une recherche/remplacement qu'une seule fois dans la valeur de l'en-tête, alors que la forme edit* en effectuera autant que le nombre d'apparition de la chaîne à remplacer.
merge
La valeur d'en-tête est ajoutée à tout en-tête de même nom, sauf si elle apparaît déjà dans la liste des valeurs préexistantes de l'en-tête séparées par des virgules. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête. Les valeurs sont comparées en tenant compte de la casse, et après le traitement de tous les spécificateurs de format. Une valeur entourée de guillemets est considérée comme différente de la même valeur mais sans guillemets.
set
L'en-tête est défini, remplaçant tout en-tête préexistant avec le même nom. L'argument valeur peut être une chaîne de formatage.
setifempty
L'en-tête est défini, mais seulement s'il n'existe aucun en-tête avec le même nom.
L'en-tête Content-Type est un cas particulier car il est possible que sa valeur ait été déterminée mais que l'en-tête ne soit pas présent dans la réponse lorsque setifempty est évalué. Dans ce cas, il est préférable d'utiliser set comme dans l'exemple suivant :
Header set Content-Type "text/plain" "expr=-z %{CONTENT_TYPE}"
unset
L'en-tête est supprimé s'il existe. Si plusieurs en-têtes possèdent le même nom, ils seront tous supprimés. L'argument value ne doit pas apparaître.
note
La valeur de l'en-tête considéré est copiée dans une note interne dont le nom est spécifié via l'argument valeur. Ceci permet de journaliser la valeur d'un en-tête envoyé par un programme CGI ou une ressource mandatée, même s'il est prévu de l'effacer.
Disponible à partir de la version 2.4.7 du serveur HTTP Apache.

Cet argument est suivi d'un nom d'en-tête qui peut se terminer par un caractère ':', mais ce n'est pas obligatoire. La casse est ignorée avec set, append, merge, add, unset et edit. Le nom d'en-tête est sensible à la casse pour echo et peut être une expression rationnelle.

Avec set, append, merge et add, une valeur est spécifiée comme argument suivant. Si valeur contient des espaces, elle doit être entourée de guillemets. valeur peut être une chaîne de caractères, une chaîne contenant des spécificateurs de format propres à mod_headers (et des caractères littéraux), ou une expression ap_expr préfixée par expr=.

valeur supporte les spécificateurs de format suivants :

Format | Description
%% | Le caractère pourcentage
%t | Le moment de réception de la requête en temps universel coordonné depuis le temps epoch (Jan. 1, 1970) et exprimé en microsecondes. La valeur est précédée de t=.
%D | Le temps écoulé entre la réception de la requête et l'envoi des en-têtes sur le réseau. Il s'agit de la durée de traitement de la requête. La valeur est précédée de D=. La valeur est exprimée en microsecondes.
%l | La charge moyenne courante du serveur proprement dit. Ce sont les valeurs obtenues par getloadavg() qui représentent la charge moyenne courante, sur 5 minutes et sur 15 minutes. Chaque valeur est précédée de l= et séparée de la suivante par un /. Disponible depuis la version 2.4.4 du serveur HTTP Apache.
%i | Le pourcentage courant de httpd au repos (de 0 à 100) en se basant sur le nombre de processus et threads disponibles. La valeur est précédée de i=. Disponible depuis la version 2.4.4 du serveur HTTP Apache.
%b | Le pourcentage courant de httpd utilisé (de 0 à 100) en se basant sur le nombre de processus et threads disponibles. La valeur est précédée de b=. Disponible depuis la version 2.4.4 du serveur HTTP Apache.
%{NOM_VARIABLE}e | Le contenu de la variable d'environnement NOM_VARIABLE.
%{NOM_VARIABLE}s | Le contenu de la variable d'environnement SSL NOM_VARIABLE, si mod_ssl est activé.

Note

Le spécificateur de format %s est disponible depuis la version 2.1 d'Apache ; il peut être utilisé à la place de %e pour éviter de devoir spécifier SSLOptions +StdEnvVars. Cependant, si SSLOptions +StdEnvVars doit tout de même être spécifié pour une raison quelconque, %e sera plus efficace que %s.

Note à propos des valeurs des expressions

Lorsque le paramètre valeur utilise l'interpréteur ap_expr, certaines syntaxes d'expressions seront différentes des exemples qui évaluent des expressions booléennes telles que <If> :

  • Le point de départ de la syntaxe est 'string' au lieu de 'expr'.
  • Les appels de fonction utilisent la syntaxe %{funcname:arg} au lieu de funcname(arg).
  • Les fonctions multi-arguments ne sont pas encore disponibles depuis le point de départ 'string'.
  • Il faut mettre entre guillemets l'ensemble du paramètre, comme dans l'exemple suivant :
    Header set foo-checksum "expr=%{md5:foo}"

editnécessite les deux arguments valeur, qui est une expression rationnelle, et une chaîne additionnelle remplacement. Depuis la version 2.4.7, la chaîne de remplacement peut aussi contenir des spécificateurs de format.

La directive Header peut être suivie d'un argument additionnel qui peut prendre les valeurs suivantes :

early
Spécifie traitement préalable.
env=[!]variable
La directive est appliquée si et seulement si la variable d'environnement variable existe. Un ! devant variable inverse le test, et la directive ne s'appliquera alors que si variable n'est pas définie.
expr=expression
La directive s'applique si et seulement si expression est évaluée à true. Vous trouverez plus de détails à propos de la syntaxe et de l'évaluation des expressions dans la documentation ap_expr.
         # Cet exemple retarde l'évaluation de la clause de condition par
     # rapport à <If>
         Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path.php$#"

Excepté le cas du mode précoce, les directives Header sont traitées juste avant l'envoi de la réponse sur le réseau. Cela signifie qu'il est possible de définir et/ou modifier la plupart des en-têtes, à l'exception de certains en-têtes qui sont ajoutés par le filtre d'en-tête HTTP. Avant la version 2.2.12, il n'était pas possible de modifier l'en-tête Content-Type avec cette directive.

Directive RequestHeader

Description: | Configure les en-têtes d'une requête HTTP
Syntaxe: | RequestHeader add|append|edit|edit*|merge|set|setifempty|unset en-tête [[expr=]valeur [remplacement] [early|env=[!]variable|expr=expression]]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_headers
Compatibilité: | SetIfEmpty est disponible depuis la version 2.4.7 du serveur HTTP Apache ; le paramètre expr=valeur a été introduit avec la version 2.4.10

Cette directive permet de remplacer, fusionner, modifier ou supprimer des en-têtes de requête HTTP. L'en-tête est modifié juste avant que le gestionnaire de contenu ne s'exécute, ce qui permet la modification des en-têtes entrants. L'action effectuée est déterminée par le premier argument. Ce dernier accepte les valeurs suivantes :

add
L'en-tête est ajouté au jeu d'en-têtes préexistant, même s'il existe déjà. Ceci peut conduire à la présence de deux (ou plusieurs) en-têtes possèdant le même nom et donc induire des conséquences imprévues ; en général, il est préférable d'utiliser set, append ou merge.
append
La valeur d'en-tête est ajoutée à tout en-tête existant de même nom. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête.
edit
edit*
Si l'en-tête existe, sa valeur est modifiée en fonction d'une expression rationnelle de type recherche/remplacement. L'argument valeur est une expression rationnelle, et l'argument remplacement une chaîne de caractères de remplacement qui peut contenir des références arrières ou des spécificateurs de format. Avec edit, la chaîne de l'en-tête correspondant au modèle ne sera recherchée et remplacée qu'une seule fois, alors qu'avec edit*, elle le sera pour chacune de ses instances si elle apparaît plusieurs fois.
merge
La valeur d'en-tête est ajoutée à tout en-tête de même nom, sauf si elle apparaît déjà dans la liste des valeurs préexistantes de l'en-tête séparées par des virgules. Lorsqu'une nouvelle valeur est ainsi ajoutée, elle est séparée de celles qui sont déjà présentes par une virgule. Il s'agit de la méthode HTTP standard permettant d'affecter plusieurs valeurs à un en-tête. Les valeurs sont comparées en tenant compte de la casse, et après le traitement de tous les spécificateurs de format. Une valeur entourée de guillemets est considérée comme différente de la même valeur mais sans guillemets.
set
L'en-tête est défini, remplaçant tout en-tête préexistant avec le même nom.
setifempty
L'en-tête est défini, mais seulement s'il n'existe aucun en-tête avec le même nom.
Disponible depuis la version 2.4.7 du serveur HTTP Apache.
unset
L'en-tête est supprimé s'il existe. Si plusieurs en-têtes possèdent le même nom, ils seront tous supprimés. L'argument value ne doit pas apparaître.

Cet argument est suivi d'un nom d'en-tête qui peut se terminer par un caractère ':', mais ce n'est pas obligatoire. La casse est ignorée. Avec set, append, merge et add, une valeur est fournie en troisième argument. Si une valeur contient des espaces, elle doit être entourée de guillemets. Avec unset, aucune valeur ne doit apparaître. valeur peut être une chaîne de caractères, une chaîne contenant des spécificateurs de format, ou une combinaison des deux. Les spécificateurs de format supportés sont les mêmes que ceux de la directive Header, à laquelle vous pouvez vous reporter pour plus de détails. Avec edit, les deux arguments valeur et remplacement sont obligatoires, et correspondent respectivement à une expression rationnelle et à une chaîne de remplacement.

La directive RequestHeader peut être suivie d'un argument supplémentaire, qui pourra prendre les valeurs suivantes :

early
Spécifie traitement préalable.
env=[!]variable
La directive est appliquée si et seulement si la variable d'environnement variable existe. Un ! devant variable inverse le test, et la directive ne s'appliquera alors que si variable n'est pas définie.
expr=expression
La directive s'applique si et seulement si expression est évaluée à true. Vous trouverez plus de détails à propos de la syntaxe et de l'évaluation des expressions dans la documentation ap_expr.

Excepté le cas du mode précoce, la directive RequestHeader est traitée juste avant la prise en compte de la requête par son gestionnaire, au cours de la phase de vérification. Ceci permet la modification des en-têtes générés par le navigateur, ou par les filtres en entrée d'Apache.


mod_heartbeat - Serveur Apache HTTP Version 2.4

Module Apache mod_heartbeat

Description: | Envoie des messages d'état au mandataire frontal
Statut: | Expérimental
Identificateur de Module: | heartbeat_module
Fichier Source: | mod_heartbeat
Compatibilité: | Disponible à partir de la version 2.3 du serveur HTTP Apache

Sommaire

mod_heartbeat envoie à un moniteur mod_heartmonitor des messages multicast l'informant du nombre de connexions courantes. En général, mod_heartmonitor est chargé sur un serveur mandataire où mod_lbmethod_heartbeat est chargé, ce qui permet d'utiliser la lbmethod "heartbeat" au sein des directives ProxyPass.

Le module mod_heartbeat est chargé sur le serveur d'origine qui sert les requêtes via le serveur mandataire.

Pour utiliser mod_heartbeat, mod_status et mod_watchdog doivent être soit des modules statiques, soit des modules dynamiques, et dans ce dernier cas, ils doivent être chargés avant mod_heartbeat.

Utilisation de la sortie de mod_heartbeat

Chaque seconde, ce module génère un paquet multicast UDP contenant le nombre de threads/processus occupés et en attente. Le paquet possède un format ASCII simple similaire aux paramètres de requête GET en HTTP.

Exemple de paquet

v=1&ready=75&busy=0

Les utilisateurs disposeront dans le futur de nouvelles variables en plus de busy et ready, et toujours séparées par des '&'.

Directive HeartbeatAddress

Description: | Adresse multicast à laquelle envoyer les requêtes heartbeat
Syntaxe: | HeartbeatAddress addr:port
Défaut: | disabled
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_heartbeat

La directive HeartbeatAddress permet de spécifier l'adresse multicast à laquelle mod_heartbeat va envoyer ses informations. En général, cette adresse correspond à la valeur définie par la directive HeartbeatListen sur le serveur mandataire frontal.

HeartbeatAddress 239.0.0.1:27999


mod_heartmonitor - Serveur Apache HTTP Version 2.4

Module Apache mod_heartmonitor

Description: | Moniteur centralisé pour les serveurs d'origine mod_heartbeat
Statut: | Expérimental
Identificateur de Module: | heartmonitor_module
Fichier Source: | mod_heartmonitor.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

mod_heartmonitor interprète les messages d'état générés par les serveurs d'origine pour lesquels mod_heartbeat est activé et fournit ces informations à mod_lbmethod_heartbeat, ce qui permet d'utiliser la lbmethod "heartbeat" au sein des directives ProxyPass.

Ce module utilise les services de mod_slotmem_shm, lorsqu'il est disponible, au lieu d'un simple fichier texte. Aucune configuration supplémentaire n'est requise pour utiliser mod_slotmem_shm.

Pour utiliser mod_heartmonitor, mod_status et mod_watchdog doivent être soit des modules statiques, soit des modules dynamiques, et dans ce dernier cas, ils doivent être chargés avant mod_heartmonitor.

Directive HeartbeatListen

Description: | Adresse multicast d'écoute des requêtes entrantes heartbeat
Syntaxe: | HeartbeatListenaddr:port
Défaut: | disabled
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_heartmonitor

La directive HeartbeatListen permet de spécifier l'adresse multicast sur laquelle le serveur va surveiller les informations d'état en provenance de serveurs où mod_heartbeat est activé. Cette adresse correspond en général à la valeur de la directive HeartbeatAddress sur le serveur d'origine.

HeartbeatListen 239.0.0.1:27999

Tant que cette directive n'est pas utilisée, le module est désactivé.

Directive HeartbeatMaxServers

Description: | Spécifie le nombre maximal de serveurs qui pourront envoyer des requêtes heartbeat à ce serveur.
Syntaxe: | HeartbeatMaxServers nombre-de-serveurs
Défaut: | HeartbeatMaxServers 10
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_heartmonitor

La directive HeartbeatMaxServers spécifie le nombre maximal de serveurs qui pourront envoyer des requêtes heartbeat à ce serveur de monitoring. Elle permet ainsi de contrôler la quantité de mémoire partagée allouée pour le stockage des données heartbeat lorsqu'on utilise mod_slotmem_shm.

Directive HeartbeatStorage

Description: | Chemin vers le stockage des données heartbeat
Syntaxe: | HeartbeatStorage chemin fichier
Défaut: | HeartbeatStorage logs/hb.dat
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_heartmonitor

La directive HeartbeatStorage permet de spécifier le chemin de stockage des données heartbeat. Ce fichier texte n'est utilisé que si mod_slotmem_shm n'est pas chargé.


mod_http2 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_http2

Description: | Support for the HTTP/2 transport layer
Status: | Extension
Module Identifier: | http2_module
Source File: | mod_http2.c
Compatibility: | Available in version 2.4.17 and later

Summary

This module provides HTTP/2 (RFC 7540) support for the Apache HTTP Server.

This module relies on libnghttp2 to provide the core http/2 engine.

You must enable HTTP/2 via Protocols in order to use the functionality described in this document. The HTTP/2 protocol does not require the use of encryption so two schemes are available: h2 (HTTP/2 over TLS) and h2c (HTTP/2 over TCP).

Two useful configuration schemes are:

HTTP/2 in a VirtualHost context (TLS only)

Protocols h2 http/1.1

Allows HTTP/2 negotiation (h2) via TLS ALPN in a secure <VirtualHost>. HTTP/2 preamble checking (Direct mode, see H2Direct) is disabled by default for h2.

HTTP/2 in a Server context (TLS and cleartext)

Protocols h2 h2c http/1.1

Allows HTTP/2 negotiation (h2) via TLS ALPN for secure <VirtualHost>. Allows HTTP/2 cleartext negotiation (h2c) upgrading from an initial HTTP/1.1 connection or via HTTP/2 preamble checking (Direct mode, see H2Direct).

Refer to the official HTTP/2 FAQ for any doubt about the protocol.

How it works

HTTP/2 Dimensioning

Enabling HTTP/2 on your Apache Server has impact on the resource consumption and if you have a busy site, you may need to consider carefully the implications.

The first noticeable thing after enabling HTTP/2 is that your server processes will start additional threads. The reason for this is that HTTP/2 gives all requests that it receives to its own Worker threads for processing, collects the results and streams them out to the client.

In the current implementation, these workers use a separate thread pool from the MPM workers that you might be familiar with. This is just how things are right now and not intended to be like this forever. (It might be forever for the 2.4.x release line, though.) So, HTTP/2 workers, or shorter H2Workers, will not show up in mod_status. They are also not counted against directives such as ThreadsPerChild. However they take ThreadsPerChild as default if you have not configured something else via H2MinWorkers and H2MaxWorkers.

Another thing to watch out for is is memory consumption. Since HTTP/2 keeps more state on the server to manage all the open request, priorities for and dependencies between them, it will always need more memory than HTTP/1.1 processing. There are three directives which steer the memory footprint of a HTTP/2 connection: H2MaxSessionStreams, H2WindowSize and H2StreamMaxMemSize.

H2MaxSessionStreams limits the number of parallel requests that a client can make on a HTTP/2 connection. It depends on your site how many you should allow. The default is 100 which is plenty and unless you run into memory problems, I would keep it this way. Most requests that browsers send are GETs without a body, so they use up only a little bit of memory until the actual processing starts.

H2WindowSize controls how much the client is allowed to send as body of a request, before it waits for the server to encourage more. Or, the other way around, it is the amount of request body data the server needs to be able to buffer. This is per request.

And last, but not least, H2StreamMaxMemSize controls how much response data shall be buffered. The request sits in a H2Worker thread and is producing data, the HTTP/2 connection tries to send this to the client. If the client does not read fast enough, the connection will buffer this amount of data and then suspend the H2Worker.

Multiple Hosts and Misdirected Requests

Many sites use the same TLS certificate for multiple virtual hosts. The certificate either has a wildcard name, such as '*.example.org' or carries several alternate names. Browsers using HTTP/2 will recognize that and reuse an already opened connection for such hosts.

While this is great for performance, it comes at a price: such vhosts need more care in their configuration. The problem is that you will have multiple requests for multiple hosts on the same TLS connection. And that makes renegotiation impossible, in face the HTTP/2 standard forbids it.

So, if you have several virtual hosts using the same certificate and want to use HTTP/2 for them, you need to make sure that all vhosts have exactly the same SSL configuration. You need the same protocol, ciphers and settings for client verification.

If you mix things, Apache httpd will detect it and return a special response code, 421 Misdirected Request, to the client.

Environment Variables

This module can be configured to provide HTTP/2 related information as additional environment variables to the SSI and CGI namespace, as well as in custom log configurations (see %{VAR_NAME}e).

Variable Name: | Value Type: | Description:
HTTP2 | flag | HTTP/2 is being used.
H2PUSH | flag | HTTP/2 Server Push is enabled for this connection and also supported by the client.
H2_PUSH | flag | alternate name for H2PUSH
H2_PUSHED | string | empty or PUSHED for a request being pushed by the server.
H2_PUSHED_ON | number | HTTP/2 stream number that triggered the push of this request.
H2_STREAM_ID | number | HTTP/2 stream number of this request.
H2_STREAM_TAG | string | HTTP/2 process unique stream identifier, consisting of connection id and stream id separated by -.

H2CopyFiles Directive

Description: | Determine file handling in responses
Syntax: | H2CopyFiles on|off
Default: | H2CopyFiles off
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.24 and later.

This directive influences how file content is handled in responses. When off, which is the default, file handles are passed from the requestion processing down to the main connection, using the usual Apache setaside handling for managing the lifetime of the file.

When set to on, file content is copied while the request is still being processed and the buffered data is passed on to the main connection. This is better if a third party module is injecting files with different lifetimes into the response.

An example for such a module is mod_wsgi that may place Python file handles into the response. Those files get close down when Python thinks processing has finished. That may be well before mod_http2 is done with them.

H2Direct Directive

Description: | H2 Direct Protocol Switch
Syntax: | H2Direct on|off
Default: | H2Direct on for h2c, off for h2 protocol
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive toggles the usage of the HTTP/2 Direct Mode. This should be used inside a <VirtualHost> section to enable direct HTTP/2 communication for that virtual host.

Direct communication means that if the first bytes received by the server on a connection match the HTTP/2 preamble, the HTTP/2 protocol is switched to immediately without further negotiation. This mode is defined in RFC 7540 for the cleartext (h2c) case. Its use on TLS connections not mandated by the standard.

When a server/vhost does not have h2 or h2c enabled via Protocols, the connection is never inspected for a HTTP/2 preamble. H2Direct does not matter then. This is important for connections that use protocols where an initial read might hang indefinitely, such as NNTP.

For clients that have out-of-band knowledge about a server supporting h2c, direct HTTP/2 saves the client from having to perform an HTTP/1.1 upgrade, resulting in better performance and avoiding the Upgrade restrictions on request bodies.

This makes direct h2c attractive for server to server communication as well, when the connection can be trusted or is secured by other means.

Example

H2Direct on

H2EarlyHints Directive

Description: | Determine sending of 103 status codes
Syntax: | H2EarlyHints on|off
Default: | H2EarlyHints off
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.24 and later.

This setting controls if HTTP status 103 interim responses are forwarded to the client or not. By default, this is currently not the case since a range of clients still have trouble with unexpected interim responses.

When set to on, PUSH resources announced with H2PushResource will trigger an interim 103 response before the final response. The 103 response will carry Link headers that advise the preload of such resources.

H2MaxSessionStreams Directive

Description: | Maximum number of active streams per HTTP/2 session.
Syntax: | H2MaxSessionStreams n
Default: | H2MaxSessionStreams 100
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of active streams per HTTP/2 session (e.g. connection) that the server allows. A stream is active if it is not idle or closed according to RFC 7540.

Example

H2MaxSessionStreams 20

H2MaxWorkerIdleSeconds Directive

Description: | Maximum number of seconds h2 workers remain idle until shut down.
Syntax: | H2MaxWorkerIdleSeconds n
Default: | H2MaxWorkerIdleSeconds 600
Context: | server config
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of seconds a h2 worker may idle until it shuts itself down. This only happens while the number of h2 workers exceeds H2MinWorkers.

Example

H2MaxWorkerIdleSeconds 20

H2MaxWorkers Directive

Description: | Maximum number of worker threads to use per child process.
Syntax: | H2MaxWorkers n
Context: | server config
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of worker threads to spawn per child process for HTTP/2 processing. If this directive is not used, mod_http2 will chose a value suitable for the mpm module loaded.

Example

H2MaxWorkers 20

H2MinWorkers Directive

Description: | Minimal number of worker threads to use per child process.
Syntax: | H2MinWorkers n
Context: | server config
Status: | Extension
Module: | mod_http2

This directive sets the minimum number of worker threads to spawn per child process for HTTP/2 processing. If this directive is not used, mod_http2 will chose a value suitable for the mpm module loaded.

Example

H2MinWorkers 10

H2ModernTLSOnly Directive

Description: | Require HTTP/2 connections to be "modern TLS" only
Syntax: | H2ModernTLSOnly on|off
Default: | H2ModernTLSOnly on
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive toggles the security checks on HTTP/2 connections in TLS mode (https:). This can be used server wide or for specific <VirtualHost>s.

The security checks require that the TSL protocol is at least TLSv1.2 and that none of the ciphers listed in RFC 7540, Appendix A is used. These checks will be extended once new security requirements come into place.

The name stems from the Security/Server Side TLS definitions at mozilla where "modern compatibility" is defined. Mozilla Firefox and other browsers require modern compatibility for HTTP/2 connections. As everything in OpSec, this is a moving target and can be expected to evolve in the future.

One purpose of having these checks in mod_http2 is to enforce this security level for all connections, not only those from browsers. The other purpose is to prevent the negotiation of HTTP/2 as a protocol should the requirements not be met.

Ultimately, the security of the TLS connection is determined by the server configuration directives for mod_ssl.

Example

H2ModernTLSOnly off

H2Push Directive

Description: | H2 Server Push Switch
Syntax: | H2Push on|off
Default: | H2Push on
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive toggles the usage of the HTTP/2 server push protocol feature.

The HTTP/2 protocol allows the server to push other resources to a client when it asked for a particular one. This is helpful if those resources are connected in some way and the client can be expected to ask for it anyway. The pushing then saves the time it takes the client to ask for the resources itself. On the other hand, pushing resources the client never needs or already has is a waste of bandwidth.

Server pushes are detected by inspecting the Link headers of responses (see https://tools.ietf.org/html/rfc5988 for the specification). When a link thus specified has the rel=preload attribute, it is treated as a resource to be pushed.

Link headers in responses are either set by the application or can be configured via mod_headers as:

mod_headers example

<Location /index.html>
    Header add Link "</css/site.css>;rel=preload"
    Header add Link "</images/logo.jpg>;rel=preload"
</Location>

As the example shows, there can be several link headers added to a response, resulting in several pushes being triggered. There are no checks in the module to avoid pushing the same resource twice or more to one client. Use with care.

HTTP/2 server pushes are enabled by default. This directive allows it to be switch off on all resources of this server/virtual host.

Example

H2Push off

Last but not least, pushes happen only when the client signals its willingness to accept those. Most browsers do, some, like Safari 9, do not. Also, pushes also only happen for resources from the same authority as the original response is for.

H2PushDiarySize Directive

Description: | H2 Server Push Diary Size
Syntax: | H2PushDiarySize n
Default: | H2PushDiarySize 256
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.19 and later.

This directive toggles the maximum number of HTTP/2 server pushes that are remembered per HTTP/2 connection. This can be used inside the <VirtualHost> section to influence the number for all connections to that virtual host.

The push diary records a digest (currently using a 64 bit number) of pushed resources (their URL) to avoid duplicate pushes on the same connection. These value are not persisted, so clients opening a new connection will experience known pushes again. There is ongoing work to enable a client to disclose a digest of the resources it already has, so the diary maybe initialized by the client on each connection setup.

If the maximum size is reached, newer entries replace the oldest ones. A diary entry uses 8 bytes, letting a default diary with 256 entries consume around 2 KB of memory.

A size of 0 will effectively disable the push diary.

H2PushPriority Directive

Description: | H2 Server Push Priority
Syntax: | H2PushPriority mime-type [after|before|interleaved] [weight]
Default: | H2PushPriority * After 16
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later. For having an effect, a nghttp2 library version 1.5.0 or newer is necessary.

This directive defines the priority handling of pushed responses based on the content-type of the response. This is usually defined per server config, but may also appear in a virtual host.

HTTP/2 server pushes are always related to a client request. Each such request/response pairs, or streams have a dependency and a weight, together defining the priority of a stream.

When a stream depends on another, say X depends on Y, then Y gets all bandwidth before X gets any. Note that this does not mean that Y will block X. If Y has no data to send, all bandwidth allocated to Y can be used by X.

When a stream has more than one dependant, say X1 and X2 both depend on Y, the weight determines the bandwidth allocation. If X1 and X2 have the same weight, they both get half of the available bandwidth. If the weight of X1 is twice as large as that for X2, X1 gets twice the bandwidth of X2.

Ultimately, every stream depends on the root stream which gets all the bandwidth available, but never sends anything. So all its bandwidth is distributed by weight among its children. Which either have data to send or distribute the bandwidth to their own children. And so on. If none of the children have data to send, that bandwidth get distributed somewhere else according to the same rules.

The purpose of this priority system is to always make use of available bandwidth while allowing precedence and weight to be given to specific streams. Since, normally, all streams are initiated by the client, it is also the one that sets these priorities.

Only when such a stream results in a PUSH, gets the server to decide what the initial priority of such a pushed stream is. In the examples below, X is the client stream. It depends on Y and the server decides to PUSH streams P1 and P2 onto X.

The default priority rule is:

Default Priority Rule

H2PushPriority * After 16

which reads as 'Send a pushed stream of any content-type depending on the client stream with weight 16'. And so P1 and P2 will be send after X and, as they have equal weight, share bandwidth equally among themselves.

Interleaved Priority Rule

H2PushPriority text/css Interleaved 256

which reads as 'Send any CSS resource on the same dependency and weight as the client stream'. If P1 has content-type 'text/css', it will depend on Y (as does X) and its effective weight will be calculated as P1ew = Xw * (P1w / 256). With P1w being 256, this will make the effective weight the same as the weight of X. If both X and P1 have data to send, bandwidth will be allocated to both equally.

With Pw specified as 512, a pushed, interleaved stream would get double the weight of X. With 128 only half as much. Note that effective weights are always capped at 256.

Before Priority Rule

H2PushPriority application/json Before

This says that any pushed stream of content type 'application/json' should be send out before X. This makes P1 dependent on Y and X dependent on P1. So, X will be stalled as long as P1 has data to send. The effective weight is inherited from the client stream. Specifying a weight is not allowed.

Be aware that the effect of priority specifications is limited by the available server resources. If a server does not have workers available for pushed streams, the data for the stream may only ever arrive when other streams have been finished.

Last, but not least, there are some specifics of the syntax to be used in this directive:

  1. '*' is the only special content-type that matches all others. 'image/*' will not work.
  2. The default dependency is 'After'.
  3. There are also default weights: for 'After' it is 16, 'interleaved' is 256.

Shorter Priority Rules

H2PushPriority application/json 32         # an After rule
H2PushPriority image/jpeg before           # weight inherited
H2PushPriority text/css   interleaved      # weight 256 default

H2PushResource Directive

Description: | Declares resources for early pushing to the client
Syntax: | H2PushResource [add] path [critical]
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.24 and later.

When added to a directory/location HTTP/2 PUSHes will be attempted for all paths added via this directive. This directive can be used several times for the same location.

This directive pushes resources much earlier than adding Link headers via mod_headers. mod_http2 announces these resources in a 103 Early Hints interim response to the client. That means that clients not supporting PUSH will still get early preload hints.

In contrast to setting Link response headers via mod_headers, this directive will only take effect on HTTP/2 connections.

By adding critical to such a resource, the server will give processing it more preference and send its data, once available, before the data from the main request.

H2SerializeHeaders Directive

Description: | Serialize Request/Response Processing Switch
Syntax: | H2SerializeHeaders on|off
Default: | H2SerializeHeaders off
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive toggles if HTTP/2 requests shall be serialized in HTTP/1.1 format for processing by httpd core or if received binary data shall be passed into the request_recs directly.

Serialization will lower performance, but gives more backward compatibility in case custom filters/hooks need it.

Example

H2SerializeHeaders on

H2StreamMaxMemSize Directive

Description: | Maximum amount of output data buffered per stream.
Syntax: | H2StreamMaxMemSize bytes
Default: | H2StreamMaxMemSize 65536
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive sets the maximum number of outgoing data bytes buffered in memory for an active streams. This memory is not allocated per stream as such. Allocations are counted against this limit when they are about to be done. Stream processing freezes when the limit has been reached and will only continue when buffered data has been sent out to the client.

Example

H2StreamMaxMemSize 128000

H2TLSCoolDownSecs Directive

Description: |
Syntax: | H2TLSCoolDownSecs seconds
Default: | H2TLSCoolDownSecs 1
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive sets the number of seconds of idle time on a TLS connection before the TLS write size falls back to small (~1300 bytes) length. This can be used server wide or for specific <VirtualHost>s.

See H2TLSWarmUpSize for a description of TLS warmup. H2TLSCoolDownSecs reflects the fact that connections may deteriorate over time (and TCP flow adjusts) for idle connections as well. It is beneficial to overall performance to fall back to the pre-warmup phase after a number of seconds that no data has been sent.

In deployments where connections can be considered reliable, this timer can be disabled by setting it to 0.

The following example sets the seconds to zero, effectively disabling any cool down. Warmed up TLS connections stay on maximum record size.

Example

H2TLSCoolDownSecs 0

H2TLSWarmUpSize Directive

Description: |
Syntax: | H2TLSWarmUpSize amount
Default: | H2TLSWarmUpSize 1048576
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2
Compatibility: | Available in version 2.4.18 and later.

This directive sets the number of bytes to be sent in small TLS records (~1300 bytes) until doing maximum sized writes (16k) on https: HTTP/2 connections. This can be used server wide or for specific <VirtualHost>s.

Measurements by google performance labs show that best performance on TLS connections is reached, if initial record sizes stay below the MTU level, to allow a complete record to fit into an IP packet.

While TCP adjust its flow-control and window sizes, longer TLS records can get stuck in queues or get lost and need retransmission. This is of course true for all packets. TLS however needs the whole record in order to decrypt it. Any missing bytes at the end will stall usage of the received ones.

After a sufficient number of bytes have been send successfully, the TCP state of the connection is stable and maximum TLS record sizes (16 KB) can be used for optimal performance.

In deployments where servers are reached locally or over reliable connections only, the value might be decreased with 0 disabling any warmup phase altogether.

The following example sets the size to zero, effectively disabling any warmup phase.

Example

H2TLSWarmUpSize 0

H2Upgrade Directive

Description: | H2 Upgrade Protocol Switch
Syntax: | H2Upgrade on|off
Default: | H2Upgrade on for h2c, off for h2 protocol
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive toggles the usage of the HTTP/1.1 Upgrade method for switching to HTTP/2. This should be used inside a <VirtualHost> section to enable Upgrades to HTTP/2 for that virtual host.

This method of switching protocols is defined in HTTP/1.1 and uses the "Upgrade" header (thus the name) to announce willingness to use another protocol. This may happen on any request of a HTTP/1.1 connection.

This method of protocol switching is enabled by default on cleartext (potential h2c) connections and disabled on TLS (potential h2), as mandated by RFC 7540.

Please be aware that Upgrades are only accepted for requests that carry no body. POSTs and PUTs with content will never trigger an upgrade to HTTP/2. See H2Direct for an alternative to Upgrade.

This mode only has an effect when h2 or h2c is enabled via the Protocols.

Example

H2Upgrade on

H2WindowSize Directive

Description: | Size of Stream Window for upstream data.
Syntax: | H2WindowSize bytes
Default: | H2WindowSize 65535
Context: | server config, virtual host
Status: | Extension
Module: | mod_http2

This directive sets the size of the window that is used for flow control from client to server and limits the amount of data the server has to buffer. The client will stop sending on a stream once the limit has been reached until the server announces more available space (as it has processed some of the data).

This limit affects only request bodies, not its meta data such as headers. Also, it has no effect on response bodies as the window size for those are managed by the clients.

Example

H2WindowSize 128000

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_ident - Serveur Apache HTTP Version 2.4

Module Apache mod_ident

Description: | Recherche d'identité conformément à la RFC 1413
Statut: | Extension
Identificateur de Module: | ident_module
Fichier Source: | mod_ident.c
Compatibilité: | Disponible depuis la version 2.2 d'Apache

Sommaire

Ce module interroge un démon compatible RFC 1413 sur un serveur distant afin de déterminer le propriétaire d'une connexion.

Traitement des bugs

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

Voir aussi

  • mod_log_config

Directive IdentityCheck

Description: | Active la journalisation de l'identité RFC 1413 de l'utilisateur distant
Syntaxe: | IdentityCheck On|Off
Défaut: | IdentityCheck Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_ident
Compatibilité: | Retiré du serveur de base depuis Apache 2.1

Cette directive permet d'activer la journalisation compatible RFC 1413 du nom de l'utilisateur distant pour chaque connexion, si la machine du client exécute identd ou un démon similaire. Cette information est enregistrée dans le journal des accès en utilisant la chaîne de formatage %...l.

Cette information ne doit pas faire l'objet d'une confiance absolue, et elle ne doit être utilisée que dans le cadre d'un traçage grossier.

Notez que de sérieux problèmes de délais peuvent survenir lors des accès à votre serveur, car chaque requête nécessite l'exécution d'un de ces processus de recherche. Lorsque des pare-feu ou des serveurs mandataires sont impliqués, chaque recherche est susceptible d'échouer et ajouter un temps de latence conformément à la directive IdentityCheckTimeout. En général, ces recherches ne se révèlent donc pas très utiles sur des serveurs publics accessibles depuis l'Internet.

Directive IdentityCheckTimeout

Description: | Détermine le délai d'attente pour les requêtes ident
Syntaxe: | IdentityCheckTimeout secondes
Défaut: | IdentityCheckTimeout 30
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_ident

Cette directive permet de spécifier le délai d'attente d'une requête ident. Une valeur par défaut de 30 secondes est recommandée par la RFC 1413, principalement pour prévenir les problèmes qui pourraient être induits par la charge du réseau. Vous pouvez cependant ajuster la valeur de ce délai en fonction du débit de votre réseau local.


mod_imagemap - Serveur Apache HTTP Version 2.4

Module Apache mod_imagemap

Description: | Traitement des cartes des zones interactives d'une image (imagemaps) au niveau du serveur
Statut: | Base
Identificateur de Module: | imagemap_module
Fichier Source: | mod_imagemap.c

Sommaire

Ce module traite les fichiers .map, et remplace ainsi la fonctionnalité du programme CGI imagemap. Tout répertoire ou type de document configuré pour utiliser le gestionnaire imap-file (à l'aide des directives AddHandler ou SetHandler), sera traité par ce module.

La directive suivante confère aux fichiers possèdant l'extension .map le statut de fichiers imagemap :

AddHandler imap-file map

Notez que la syntaxe suivante reste encore supportée :

AddType application/x-httpd-imap map

Cependant, nous essayons d'abandonner progressivement les "types MIME magiques", et cette syntaxe est sur le point de devenir obsolète.

Nouvelles fonctionnalités

Le module imagemap propose quelques nouvelles fonctionnalités qui n'étaient pas disponibles avec les programmes imagemap précédemment distribués.

  • Références d'URLs relatives à l'information contenue dans l'en-tête Referer: .
  • Assignement <base> par défaut via la nouvelle directive base.
  • Fichier imagemap.conf non requis.
  • Références à des points.
  • Génération configurable de menus d'images interactives.

Fichier imagemap

Les lignes d'un fichier imagemap peuvent se présenter sous plusieurs formats :

directive valeur [x,y ...]
directive valeur "Texte de menu" [x,y ...]
directive valeur x,y ... "Texte de menu"

Les directives sont base, default, poly, circle, rect, ou point. valeur est une URL absolue ou relative, ou une des valeurs spéciales énumérées ci-dessous. Les coordonnées sont des paires x,y séparées par des espaces. Le texte entre guillemets est le texte du lien si un menu imagemap est généré. Les lignes commençant par '#' sont des commentaires.

Directives d'un fichier imagemap

Les directives autorisées dans un fichier imagemap sont au nombre de six. Elles peuvent se trouver à n'importe quelle position dans le fichier, mais sont traitées dans l'ordre selon lequel elles sont enregistrées dans le fichier imagemap.

Directive base

Elle a le même effet que <base href="valeur">. Les URLs non absolues du fichier imagemap sont considérées comme relatives à cette valeur. La directive base l'emporte sur une directive ImapBase définie dans un fichier .htaccess ou dans le fichier de configuration du serveur. En l'absence de directive de configuration ImapBase, la valeur par défaut de base est http://nom_serveur/.

base_uri est un synonyme de base. Notez que la présence ou l'absence d'un slash de fin dans l'URL est importante.

Directive default
La décision à prendre si les coordonnées fournies ne correspondent à aucune des directives poly, circle, ou rect, et si aucune directive point n'est présente. En l'absence de définition d'une directive de configuration ImapDefault, la valeur par défaut est nocontent et provoque l'envoi d'un code de statut 204 No Content. Le client verra toujours la même page s'afficher.
Directive poly
Accepte comme arguments trois à cent points, et est actionnée si les coordonnées sélectionnées par l'utilisateur tombent dans le polygone défini par ces points.
Directive circle
Accepte comme arguments les coordonnées du centre d'un cercle et celles d'un point de ce cercle. Elle est actionnée si les coordonnées sélectionnées par l'utilisateur tombent dans ce cercle.
Directive rect
Accepte comme arguments les coordonnées des sommets de deux angles opposés d'un rectangle. Elle est actionnée si les coordonnées sélectionnées par l'utilisateur tombent dans ce rectangle.
Directive point
Elle n'accepte qu'un seul point comme argument. Si aucune autre directive ne correspond, c'est la directive dont le point spécifié est le plus près du point sélectionné par l'utilisateur qui est actionnée. Notez que la directive default ne sera pas suivie si une directive point est présente et si des coordonnées valides sont fournies.

Valeurs

Les valeurs passées aux directives peuvent contenir :

une URL

L'URL peut être absolue ou relative. Les URLs relatives peuvent contenir '..' et seront considérées comme relatives à la valeur de base.

base en lui-même, ne sera pas résolu en fonction de la valeur courante. Cependant, une directive base mailto: fonctionnera correctement.

map
Équivalent à l'URL du fichier imagemap lui-même. Aucune coordonnée n'est spécifiée, et un menu sera donc généré, à moins qu'une directive ImapMenu n'ait été définie à none.
menu
Équivalent à map.
referer
Équivalent à l'URL du document référant. La valeur par défaut est http://nom_serveur/ si aucun en-tête Referer: n'est présent.
nocontent
Envoie un code de statut 204 No Content, indiquant au client qu'il doit continuer à afficher la même page. Valide pour toutes les directives, sauf base.
error
Envoie un code de statut d'échec 500 Server Error. Valide pour toutes les directives, sauf base, mais n'a de sens qu'avec la directive default.

Coordonnées

0,0 200,200
Une coordonnée se compose de deux valeurs, x et y, séparées par une virgule. Les coordonnées sont séparées entre elles par des espaces. Pour s'adapter à la manière dont Lynx traite les images interactives, la sélection par un utilisateur de la coordonnée 0,0 a le même effet que si aucune coordonnée n'a été sélectionnée.

Texte entre guillemets

"Texte du menu"

Après la valeur ou les coordonnées, la ligne peut éventuellement contenir un texte entre guillemets. Cette chaîne constitue le texte du lien si un menu est généré :

<a href="http://example.com/">Texte de menu</a>

Si aucun texte entre guillemets n'est présent, le texte sera constitué du nom du lien :

<a href="http://example.com/">http://example.com</a>

Si vous voulez insérer des guillemets dans le texte, vous devez les inscrire sous la forme &quot;.

Exemple de fichier imagemap

#Les commentaires sont affichés dans un menu 'formaté' ou #'semi-formaté'.
#Et peuvent contenir des balises html. <hr>
base referer
poly map "Puis-je avoir un menu, s'il vous plait ?" 0,0 0,10 10,10 10,0
rect .. 0,0 77,27 "le répertoire du référant"
circle http://www.inetnebr.example.com/lincoln/feedback/ 195,0 305,27
rect autre_fichier "dans le même répertoire que le référant" 306,0 419,27
point http://www.zyzzyva.example.com/ 100,100
point http://www.tripod.example.com/ 200,200
rect mailto:nate@tripod.example.com 100,150 200,0 "Bogues?"

Référencement de votre fichier imagemap

Exemple HTML

<a href="/maps/imagemap1.map">
<img ismap src="/images/imagemap1.gif">
 </a>

Exemple XHTML

<a href="/maps/imagemap1.map">
<img ismap="ismap" src="/images/imagemap1.gif" />
 </a>

Directive ImapBase

Description: | Valeur par défaut de la directive base des fichiers imagemap
Syntaxe: | ImapBase map|referer|URL
Défaut: | ImapBase http://nom_serveur/
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_imagemap

La directive ImapBase permet de définir la valeur par défaut de la directive base des fichiers imagemap. Sa valeur est écrasée par la présence éventuelle d'une directive base dans le fichier imagemap. Si cette directive est absente, la valeur par défaut de la directive base est http://nom_serveur/.

Voir aussi

  • UseCanonicalName

Directive ImapDefault

Description: | Action à entreprendre par défaut lorsqu'un fichier imagemap est invoqué avec des coordonnées qui ne correspondent à aucune cible
Syntaxe: | ImapDefault error|nocontent|map|referer|URL
Défaut: | ImapDefault nocontent
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_imagemap

La directive ImapDefault permet de définir la valeur par défaut de la directive default utilisée dans les fichiers imagemap. Sa valeur est écrasée par la présence éventuelle d'une directive default dans le fichier imagemap. Si cette directive est absente, l'action associée à default est nocontent, ce qui implique l'envoi d'un code de statut 204 No Content au client. Dans ce cas, le client doit continuer à afficher la même page.

Directive ImapMenu

Description: | Action à entreprendre si aucune coordonnée n'est fournie lorsqu'on invoque un fichier imagemap
Syntaxe: | ImapMenu none|formatted|semiformatted|unformatted
Défaut: | ImapMenu formatted
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Indexes
Statut: | Base
Module: | mod_imagemap

La directive ImapMenu permet de spécifier l'action à entreprendre lorsqu'un fichier imagemap est invoqué sans coordonnées valides.

none
Si l'argument d'ImapMenu est none, aucun menu n'est généré, et l'action default est effectuée.
formatted
Le menu formatted est le menu le plus simple. Les commentaires du fichier imagemap sont ignorés. Un en-tête de niveau un est affiché, puis un séparateur horizontal, puis chacun des liens sur une ligne séparée. L'aspect du menu est similaire à celui d'un listing de répertoire.
semiformatted
Dans le menu semiformatted, les commentaires sont affichés au moment où ils apparaissent dans le fichier imagemap. Les lignes vides sont interprètées comme des lignes de séparation HTML. Aucun en-tête ni séparateur horizontal n'est affiché. À part ces différences, le menu semiformatted est identique au menu formatted.
unformatted
Les commentaires sont affichés et les lignes vides sont ignorées. N'est affiché que ce qui apparait dans le fichier imagemap. Toutes les lignes de séparation HTML et les en-têtes doivent être inclus en tant que commentaires dans le fichier imagemap. Cela vous procure une grande souplesse pour définir l'apparence de vos menus, mais vous oblige à rédiger vos fichiers imagemap en HTML, et non en texte plat.


mod_include - Serveur Apache HTTP Version 2.4

Module Apache mod_include

Description: | Documents html interprétés par le serveur (Server Side Includes ou SSI)
Statut: | Base
Identificateur de Module: | include_module
Fichier Source: | mod_include.c

Sommaire

Ce module fournit un filtre qui va traiter les fichiers avant de les envoyer au client. Le traitement est contrôlé via des commentaires SGML spécialement formatés, aussi nommés éléments. Ces éléments permettent l'insertion conditionnelle de texte, l'inclusion d'autres fichiers ou programmes, ainsi que la définition et l'affichage de variables d'environnement.

Traitement des bugs

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

Voir aussi

  • Options
  • AcceptPathInfo
  • Les filtres
  • Tutoriel SSI

Activation des SSI

Les SSI sont implémentés par le filtre INCLUDES. Si des documents contenant des directives SSI possèdent une extension .shtml, les directives suivantes indiqueront à Apache de les interpréter et d'assigner le type MIME text/html au document obtenu :

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

L'option suivante doit être définie pour les répertoires qui contiennent les fichiers shtml (en général dans une section <Directory>, mais cette option peut également être définie dans un fichier .htaccess si AllowOverride Options a été défini pour le répertoire considéré) :

Options +Includes

Pour des raisons de compatibilité ascendante, le gestionnaire server-parsed peut aussi activer le filtre INCLUDES. Ainsi, Apache va activer le filtre INCLUDES pour tout document de type MIME text/x-server-parsed-html ou text/x-server-parsed-html3 (et le document obtenu aura pour type MIME text/html).

Pour plus d'informations, voyez notre Tutoriel SSI.

PATH_INFO et SSI

Les fichiers traités dans le cadre des SSI n'acceptent plus par défaut les requêtes avec PATH_INFO (les informations relatives au chemin en fin de requête). La directive AcceptPathInfo permet de configurer le serveur de façon à ce qu'il accepte ce genre de requête.

Eléments disponibles

Le document est interprété comme un document HTML, avec des commandes spéciales incluses sous forme de commentaires SGML. La syntaxe d'une commande est la suivante :

<!--#élément attribut=valeur attribut=valeur ... -->

Les valeurs sont souvent entourées de guillemets, mais on peut aussi utiliser des apostrophes (') ou des apostrophes inverses (`). De nombreuses commandes n'acceptent qu'une seule paire attribut-valeur. Notez que le terminateur de commentaire (-->) doit être précédé d'un espace afin d'être sûr qu'il ne soit pas considéré comme un élément de commande SSI. Notez aussi que le délimiteur de début <!--# est un élément de commande et ne doit donc pas contenir d'espace.

La table suivante contient la liste des éléments autorisés :

Elément | Description
comment | commentaire SSI
config | configure les formats de sortie
echo | affiche le contenu de variables
exec | exécute des programmes externes
fsize | affiche la taille d'un fichier
flastmod | affiche la date de dernière modification d'un fichier
include | inclut un fichier
printenv | affiche toutes les variables disponibles
set | définit la valeur d'une variable

Les éléments SSI peuvent être définis par d'autres modules que mod_include. À ce titre, l'élément exec est fourni par mod_cgi, et ne sera disponible que si ce module est chargé.

L'élément comment

Cette commande n'affiche aucune information. Elle n'a pour but que l'ajout de commentaires dans un fichier et ces commentaires ne sont pas affichés.

Cette syntaxe est disponible à partir de la version 2.4.21 du serveur HTTP Apache.

<!--#comment Blah Blah Blah -->

L'élément config

Cette commande contrôle divers aspects de l'interprétation. Les attributs valides sont :

echomsg (Versions 2.1 et supérieures d'Apache)

La valeur est un message qui sera envoyé au client si l'élément echo tente d'afficher le contenu d'une variable non définie. Cet attribut l'emporte sur toute directive SSIUndefinedEcho.

<!--#config echomsg="[Valeur non définie]" -->

errmsg

La valeur est un message qui sera envoyé au client si une erreur survient lors de l'interprétation du document. Cet attribut l'emporte sur toute directive SSIErrorMsg.

<!--#config errmsg="[Zut, quelque chose s'est mal passé.]" -->

sizefmt

La valeur définit l'unité employée lors de l'affichage de la taille d'un fichier. Les valeurs possibles sont bytes pour une taille en octets, ou abbrev pour une taille en Ko ou Mo selon son importance ; par exemple, une taille de 1024 octets sera affichée sous la forme "1K".

<!--#config sizefmt="abbrev" -->

timefmt

La valeur est une chaîne que pourra utiliser la fonction de la bibliothèque standard strftime(3) lors de l'affichage des dates.

<!--#config timefmt=""%R, %B %d, %Y"" -->

L'élément echo

Cette commande affiche le contenu d'une des variables include définies ci-dessous. Si la variable n'est pas définie, le résultat est déterminé par la valeur de la directive SSIUndefinedEcho. Le format d'affichage des dates est défini par l'attribut timefmt de la commande config.

Attributs:

var
La valeur est le nom de la variable à afficher.
decoding

Spécifie si Apache doit effectuer un décodage dans la variable avant son traitement ultérieur. La valeur par défaut est none, et dans ce cas, aucun décodage n'est effectué. Si la valeur est url, un décodage de type URL sera effectué (il s'agit du codage de type %-encoding utilisé dans les URLs des liens, etc...). Si la valeur est urlencoded, c'est un décodage des éléments de type application/x-www-form-urlencode (que l'on trouve dans les chaînes de paramètres) qui sera effectué. Si la valeur est base64, un decodage de type base64 sera effectué, et si elle est entity, c'est un décodage des entités HTML qui sera effectué. Ce décodage est effectué avant tout codage ultérieur de la variable. Il est possible d'effectuer plusieurs décodages en spécifiant plusieurs valeurs séparées par des virgules. Les spécifications de décodages restent valables jusqu'au prochain attribut de décodage, ou la fin de l'élément.

Pour être pris en compte, l'attribut de décodage doit précéder l'attribut var correspondant.

encoding

Spécifie la manière dont Apache va coder les caractères spéciaux que la variable contient avant leur affichage. S'il est défini à none, aucun codage ne sera effectué. S'il est défini à url, un codage de type URL sera effectué (aussi connu sous le nom de codage avec caractères % , il convient pour les URLS des liens, etc...). S'il est défini à urlencoded, c'est un codage compatible application/x-www-form-urlencoded qui sera effectué (à utiliser dans les chaînes de paramètres). S'il est défini à base64, c'est un encodage de type base64 qui sera effectué. Au début d'un élément echo, la valeur par défaut est définie à entity, ce qui correspond à un codage de type entité (codage qui convient pour un élément HTML de type bloc, comme le paragraphe d'un texte). Cette valeur par défaut peut être modifiée en ajoutant un attribut encoding, qui fera effet jusqu'à la définition d'un nouvel attribut encoding ou la fin de l'élément echo.

Pour produire son effet, l'attribut encoding doit précéder l'attribut var concerné.

Afin de prévenir les attaques de type cross-site scripting, il est recommandé de toujours encoder les données fournies par les utilisateurs.

Example

<!--#echo encoding="entity" var="QUERY_STRING" -->

L'élément exec

La commande exec exécute la commande shell ou le script spécifié. Elle nécessite le chargement du module mod_cgi. Si Options IncludesNOEXEC est définie, cette commande est désactivée. Les attributs disponibles sont :

cgi

La valeur spécifie un chemin URL vers le script CGI (encodé avec caractères %). Si le chemin ne commence pas par un slash (/), il est considéré comme relatif au document courant. Le document référencé par ce chemin est invoqué en tant que script CGI, même s'il n'est pas censé être reconnu comme tel par le serveur. Les scripts CGI doivent cependant être activés dans le répertoire qui contient les scripts (via la directive ScriptAlias ou l'Options ExecCGI).

Le PATH_INFO et la chaîne d'arguments (QUERY_STRING) de la requête originale du client sont fournis au script CGI ; ils ne peuvent pas être spécifiés dans le chemin de l'URL. Le script disposera des variables include en plus de l'environnement standard CGI.

Exemple

<!--#exec cgi="/cgi-bin/exemple.cgi" -->

Si, à la place d'un flux de sortie, le script renvoie un en-tête Location:, ce dernier sera traduit en ancrage HTML.

L'élément include virtual doit être préféré à exec cgi. En particulier, si vous devez transmettre des arguments supplémentaires à un programme CGI en utilisant la chaîne d'arguments de la requête, c'est impossible avec exec cgi, mais vous pouvez y parvenir avec include virtual comme suit :

<!--#include virtual="/cgi-bin/exemple.cgi?argument=valeur" -->

cmd

Le serveur va exécuter la commande fournie en utilisant /bin/sh. La commande dispose des variables include, en plus du jeu habituel de variables CGI.

Il est toujours préférable d'utiliser #include virtual à la place de #exec cgi ou #exec cmd. #include virtual utilise le mécanisme standard des sous-requêtes d'Apache pour inclure des fichiers ou des scripts. Il a fait l'objet de tests plus approfondis et sa maintenance est mieux suivie.

De plus, sur certaines plate-formes, comme Win32, et sous unix, si l'on utilise suexec, il est impossible de transmettre des arguments à une commande dans une directive exec, à moins d'insérer des espaces dans la commande. Ainsi, alors que ce qui suit fonctionnera sous unix avec une configuration sans suexec, l'effet produit ne sera pas celui désiré sous Win32, ou dans le cas de l'utilisation de suexec :

<!--#exec cmd="perl /chemin/vers/script_perl arg1 arg2" -->

L'élément fsize

Cette commande permet d'afficher la taille du fichier spécifié en fonction des spécifications de format de sizefmt. Attributs :

file
La valeur est le chemin du fichier, relatif au répertoire contenant le document en cours d'interprétation.

Ce fichier a une taille de <!--#fsize file="mod_include.html" --> octets.

La valeur de file ne peut pas faire référence à un fichier situé à un niveau supérieur de l'arborescence du répertoire courant ou en dehors de la racine des documents ; il ne peut donc ni commencer par un slash, ni contenir la séquence de caractères ../. Si c'est le cas, le message d'erreur The given path was above the root path sera renvoyé.
virtual
La valeur est un chemin URL (codé avec caractères %). S'il ne commence pas par un slash (/), il est considéré comme relatif au document courant. Notez que cette commande n'affiche pas la taille de la sortie d'un programme CGI, mais la taille du programme CGI lui-même.

Ce fichier a une taille de <!--#fsize virtual="/docs/mod/mod_include.html" --> octets.

Notez que dans la plupart des cas, ces deux attributs sont identiques. Cependant, l'attribut file ne respecte pas les aliases URL-space.

L'élément flastmod

Cette commande permet d'afficher la date de dernière modification du fichier spécifié, en fonction des spécifications de format de timefmt. Les attributs sont les mêmes que ceux de la commande fsize.

L'élément include

Cette commande permet d'insérer le texte d'un autre document ou fichier dans le fichier en cours d'interprétation. Tout fichier inclus est soumis au contrôle d'accès habituel. Si Options IncludesNOEXEC est défini pour le répertoire contenant le fichier interprété, seuls les documents possèdant un type MIME de type texte (text/plain, text/html, etc...) seront inclus. Les scripts CGI, quant à eux, sont invoqués de manière habituelle en utilisant l'URL complète fournie avec la commande, y compris toute chaîne d'arguments éventuelle.

Un attribut définit le chemin du document à inclure, et peut apparaître plusieurs fois dans l'élément à inclure ; en retour, pour chaque attribut fourni à la commande include, une inclusion est effectuée. Les attributs disponibles sont :

file
La valeur est un chemin relatif au répertoire contenant le fichier en cours d'interprétation. Elle ne peut ni contenir ../, ni être un chemin absolu. Ainsi, vous ne pouvez pas inclure de fichiers situés en dehors de l'arborescence du site web ou dans un niveau supérieur à celui du fichier courant dans cette arborescence. Il est toujours préférable d'utiliser l'attribut virtual.
virtual

La valeur est un chemin URL (codé avec caractères %). L'URL ne peut contenir qu'un chemin et une chaîne d'arguments éventuelle, à l'exclusion de tout protocole ou nom d'hôte. S'il ne commence pas par un slash (/), il est considéré comme relatif au document courant.

Une URL est construite à partir de l'attribut, et la sortie que renverrait le serveur si l'URL était accédée par le client est incluse dans la sortie interprétée. Les inclusions de fichiers peuvent ainsi être imbriquées.

Si l'URL spécifiée correspond à un programme CGI, le programme sera exécuté, et son flux de sortie inséré à la place de la directive dans le fichier interprété. Vous pouvez insérer une chaîne d'arguments dans une URL correspond à un programme CGI :

<!--#include virtual="/cgi-bin/exemple.cgi?argument=valeur" -->

include virtual doit être préféré à exec cgi pour inclure le flux de sortie d'un programme CGI dans un document HTML.

Si la directive KeptBodySize est correctement définie et valide pour le fichier inclus, les tentatives de requêtes POST vers le document HTML qui inclut des fichiers seront transmises aux sous-requêtes en tant que requêtes POST elles-mêmes. Sans cette directive, toutes les sous-requêtes sont traitées en tant que requêtes GET.

onerror

La valeur est un chemin-URL (codé-%) qui est affiché si une tentative précédente d'inclure un fichier ou un attribut virtuel a échoué. Pour produire son effet, cet attribut doit être spécifié après le fichier ou les attributs virtuels concernés. Si la tentative d'inclure le chemin onerror échoue, ou si onerror n'est pas spécifié, c'est le message d'erreur par défaut qui sera inclus.

# Exemple simple
<!--#include virtual="/not-exist.html" onerror="/error.html" -->

# Chemins onerror dédiés
<!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->

L'élément printenv

Cette commande affiche la liste en mode texte de toutes les variables et de leurs valeurs. Les caractères spéciaux sont encodés entity avant d'être affichés (se reporter à l'élément echo pour plus de détails). Cette commande ne comporte pas d'attributs.

Exemple

<pre> <!--#printenv --> </pre>

L'élément set

Cette commande permet de définir la valeur d'une variable. Les attributs sont :

var
Le nom de la variable à définir.
value
La valeur à affecter à la variable.
decoding

Spécifie si Apache doit effectuer un décodage dans la variable avant son traitement ultérieur. La valeur par défaut est none, et dans ce cas, aucun décodage n'est effectué. Si la valeur est url, urlencoded, base64 ou entity, c'est un décodage de type URL, application/x-www-form-urlencoded, base64 ou entité HTML qui sera respectivement effectué. Il est possible d'effectuer plusieurs décodages en spécifiant plusieurs valeurs séparées par des virgules. Les spécifications de décodages restent valables jusqu'au prochain attribut de décodage, ou la fin de l'élément. Pour être pris en compte, l'attribut de décodage doit précéder l'attribut var correspondant.

encoding

Spécifie la manière dont Apache va encoder les caractères spéciaux que la variable contient avant leur affichage. S'il est défini à none, aucun encodage ne sera effectué. Si la valeur est url, urlencoding, base64 ou entity, c'est un encodage de type URL, application/x-www-form-urlencoded, base64 ou entité HTML qui sera respectivement effectué. Il est possible de spécifier plusieurs types d'encodage en les séparant par des virgules. La spécification du type d'encodage fera effet jusqu'à la définition d'un nouvel attribut encoding ou la fin de l'élément. Pour produire son effet, l'attribut encoding doit précéder l'attribut var concerné. Les encodages sont effectués après les opérations de décodage.

Exemple

<!--#set var="category" value="help" -->

Variables include

À l'instar des variables de l'environnement CGI standard, ces variables sont mises à la disposition de la commande echo, des opérateurs conditionnels if et elif, et de tout programme invoqué par le document.

DATE_GMT
La date GMT (Greenwich Mean Time) courante.
DATE_LOCAL
La date locale courante.
DOCUMENT_ARGS
Cette variable contient la chaîne de paramètres de la requête du document SSI actif, ou la chaîne vide si aucune chaîne de paramètres de requête n'est incluse. Pour les sous-requêtes invoquées par la directive SSI include, QUERY_STRING contiendra la chaîne de paramètres de la sous-requête et DOCUMENT_ARGS la chaîne de paramètres du document SSI (disponible à partir de la version 2.4.19 du serveur HTTP Apache).
DOCUMENT_NAME
Le nom de base du fichier demandé par l'utilisateur (sans son chemin).
DOCUMENT_URI
Le chemin URL (caractères % décodés) du document demandé par l'utilisateur. Notez que dans le cas d'inclusions de fichiers imbriquées, il ne s'agit pas de l'URL du document courant. Notez également que si l'URL est modifiée en interne (par exemple via une directive alias ou directoryindex), c'est l'URL modifiée que contiendra la variable.
LAST_MODIFIED
La date de dernière modification du document demandé par l'utilisateur.
QUERY_STRING_UNESCAPED
Si une chaîne d'arguments est présente dans la requête pour le document SSI actif, elle sera affectée à cette variable, les caractères %-décodés, et éventuellement échappés pour qu'ils ne soient pas interprétés par le shell (les caractères spéciaux comme &,etc... sont précédés d'anti-slashes). Cette variable n'est pas définie si aucune chaîne d'arguments n'est présente. Utilisez DOCUMENT_ARGS si l'échappement des caractères du shell n'est pas souhaité.

Substitution de variable

Une substitution de variable à l'intérieur d'une chaîne entre guillemets s'effectue dans la plupart des situations où cette dernière peut raisonablement constituer un argument d'une directive SSI. Sont concernées les directives config, exec, flastmod, fsize, include, echo, et set. Si la directive SSILegacyExprParser est définie à on, la substitution s'effectue aussi dans les arguments des opérateurs conditionnels. Vous pouvez insérer un signe dollar en tant que caractère littéral dans une chaîne en utilisant un anti-slash :

<!--#set var="cur" value="\$test" -->

Si une référence de variable doit être substituée au beau milieu d'une séquence de caractères qui pourrait être elle-même considérée comme un identifiant valide, l'ambiguïté peut être levée en entourant la référence d'accolades, à la manière du shell :

<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

Dans cet exemple, la variable Zed se verra affecter la valeur "X_Y" si REMOTE_HOST et REQUEST_METHOD contiennent respectivement "X" et "Y".

Eléments de contrôle d'inclusion conditionnelle

Les éléments de base du contrôle d'inclusion conditionnelle sont :

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

L'élément if fonctionne de la même manière que la directive if d'un langage de programmation. La condition est évaluée et si le résultat est vrai, le texte qui suit jusqu'au prochain élément elif, else ou endif sera inclus dans le flux de sortie.

Les éléments elif ou else permettent d'insérer du texte dans le flux de sortie si test_condition s'est révélé faux. Ces éléments sont optionnels.

L'élément endif termine le bloc de traitement conditionnel if et est obligatoire.

test_condition est une expression booléenne qui emprunte la syntaxe ap_expr. La directive SSILegacyExprParser permet de modifier cette syntaxe pour la rendre compatible avec Apache HTTPD 2.2.x.

Le jeu de variables SSI avec l'élément var sont exportées vers l'environnement de la requête et sont accessibles via la fonction reqenv. Pour faire simple, le nom de fonction v est aussi disponible dans le module mod_include.

Dans l'exemple suivant, "depuis le réseau local" sera affiché si l'adresse IP du client appartient au sous-réseau 10.0.0.0/8.

<!--#if expr='-R "10.0.0.0/8"' -->
depuis le réseau local
 <!--#else -->
depuis ailleurs
 <!--#endif -->

Dans l'exemple suivant, "foo vaut bar" sera affiché si la variable foo contient la valeur "bar".

<!--#if expr='v("foo") = "bar"' -->
foo vaut bar
 <!--#endif -->

Documentation de référence

Voir aussi Les expressions dans le serveur HTTP Apache pour une référence complète et des exemples. Les fonctions restricted ne sont pas disponibles dans mod_include.

Syntaxe des expressions héritée

Cette section décrit la syntaxe de l'élément #if expr dans le cas où la directive SSILegacyExprParser est définie à on.

chaîne
vrai si chaîne n'est pas vide
-A string

vrai si l'URL que contient la chaîne est accessible du point de vue de la configuration, faux sinon. Il s'avère utile lorsqu'un lien vers une URL doit être caché aux utilisateurs qui ne sont pas autorisés à voir cette URL. Notez que le test porte sur l'autorisation d'accès à l'URL, et non sur son existence.

Exemple

<!--#if expr="-A /prive" -->
Cliquez <a href="/prive">ici</a> pour accéder aux informations privées.
 <!--#endif -->

chaîne1 = chaîne2
chaîne1 == chaîne2
chaîne1 != chaîne2

Compare chaîne1 à chaîne2. Si chaîne2 est de la forme /chaîne2/, elle est traitée comme une expression rationnelle. Les expressions rationnelles sont implémentées par le moteur PCRE et possèdent la même syntaxe que celles de perl 5. Notez que == n'est qu'un alias pour = et se comporte exactement de la même manière que ce dernier.

Si vous faites une comparaison directe (= ou ==), vous pouvez extraire des parties de l'expression rationnelle. Les parties extraites sont stockées dans les variables spéciales $1 .. $9. L'ensemble de la chaîne correspondant à l'expression rationnelle est stocké dans la variable spéciale $0.

Exemple

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
 <!--#endif -->

chaîne1 < chaîne2
chaîne1 <= chaîne2
chaîne1 > chaîne2
chaîne1 >= chaîne2
Compare chaîne1 à chaîne2. Notez que les chaînes sont comparées de manière littérale (en utilisant strcmp(3)). Ainsi, la chaîne "100" est inférieure à "20".
( test_condition )
vrai si test_condition est vrai
! test_condition
vrai si test_condition est faux
test_condition1 && test_condition2
vrai si test_condition1 et test_condition2 sont tous les deux vrais
test_condition1 || test_condition2
vrai si au moins un des tests test_condition1 ou test_condition2 est vrai

"=" et "!=" ont une priorité supérieure à "&&" et "||". "!" a la priorité la plus haute. Ainsi, les deux directives suivantes sont équivalentes :

<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->

Les opérateurs booléens && et || ont la même priorité. Ainsi, si vous voulez augmenter la priorité d'un de ces opérateurs, vous devez utiliser des parenthèses.

Tout ce qui n'est pas reconnu comme variable ou opérateur est traité comme une chaîne. Les chaînes peuvent aussi être entourées d'apostrophes : 'chaîne'. Les chaînes sans apostrophe ne peuvent pas contenir d'espaces (espaces ou tabulations) car ceux-ci servent à séparer certains éléments comme les variables. Si plusieurs chaînes se trouvent dans une ligne, elles sont concaténées en utilisant des espaces. Ainsi,

chaîne1    chaîne2 devient chaîne1 chaîne2

et

'chaîne1    chaîne2' devient chaîne1    chaîne2.

Optimisation des expressions booléennes

Si les expressions atteignent une complexité suffisante pour ralentir les traitements de manière significative, vous pouvez essayer de les optimiser en fonction des règles d'évaluation :

  • Les expressions sont évaluées de la gauche vers la droite
  • Les opérateurs booléens binaires (&& et ||) font l'objet d'une évaluation abrégée chaque fois que cela est possible. En d'autres termes, et selon la règle ci-dessus, mod_include évalue tout d'abord la partie gauche de l'expression. Si le résultat de l'évaluation de cette partie gauche suffit à déterminer le résultat final, l'évaluation s'arrête ici. Dans le cas contraire, la partie droite est évaluée, et le résultat final tient compte des résultats des évaluations des parties gauche et droite.
  • L'évaluation abrégée est désactivée tant qu'il reste des expressions régulières à traiter. Ces dernières doivent être évaluées afin de définir les variables correspondant aux références arrières ($1 .. $9).

Si vous voulez déterminer la manière dont une expression est traitée, vous pouvez recompiler mod_include en utilisant l'option de compilation -DDEBUG_INCLUDE. Ceci a pour effet d'insérer, pour chaque expression interprétée, des informations étiquetées, l'arbre d'interprétation et la manière dont elle est évaluée au sein du flux de sortie envoyé au client.

Slashes d'échappement dans les expressions rationnelles

Tous les caractères slashes qui ne sont pas des séparateurs dans votre expression rationnelle doivent être échappés, et ceci sans tenir compte de leur signification du point de vue du moteur d'expressions rationnelles.

Documentation de référence

Voir le document Les expressions dans le serveur HTTP Apache, pour une référence complète et des exemples.

Directive SSIEndTag

Description: | Chaîne qui termine l'élément include
Syntaxe: | SSIEndTag tag
Défaut: | SSIEndTag "-->"
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_include

Cette directive permet de modifier la chaîne que mod_include interprète comme la fin d'un élément include.

SSIEndTag "%>"

Voir aussi

  • SSIStartTag

Directive SSIErrorMsg

Description: | Message d'erreur affiché lorsqu'une erreur SSI survient
Syntaxe: | SSIErrorMsg message
Défaut: | SSIErrorMsg "[an error occurred while processing this directive]"
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Base
Module: | mod_include

La directive SSIErrorMsg permet de modifier le message d'erreur affiché lorsqu'une erreur SSI survient. Pour les serveurs en production, il est recommandé de modifier le message d'erreur par défaut en "<!-- Error -->", de façon à ce que le message ne soit pas présenté à l'utilisateur.

Cette directive a le même effet que l'élément <!--#config errmsg=message -->.

SSIErrorMsg "<!-- Error -->"

Directive SSIETag

Description: | Définit si des en-têtes ETags sont générés par le serveur.
Syntaxe: | SSIETag on|off
Défaut: | SSIETag off
Contexte: | répertoire, .htaccess
Statut: | Base
Module: | mod_include
Compatibilité: | Disponible à partir de la version 2.2.15 du serveur HTTP Apache.

Dans le cas général, un fichier filtré par mod_include peut contenir des éléments soit générés dynamiquement, soit éventuellement modifiés indépendemment du fichier original. En conséquence, il est demandé par défaut au serveur de ne pas générer d'en-tête ETag à la réponse en ajoutant no-etag aux informations de requête.

Ce comportement peut être modifié via la directive SSIETag qui permet au serveur de générer un en-tête ETag. On peut aussi l'utiliser pour la mise en cache de la sortie. Notez qu'un serveur d'arrière-plan ou un générateur de contenu dynamique peut lui-même générer un en-tête ETag, en ignorant l'information no-etag, cet en-tête ETag étant transmis par mod_include sans tenir compte de la définition de la présente directive. La directive SSIETag peut prendre une des valeurs suivantes :

off
no-etag sera ajouté aux informations de requête, et il sera demandé au serveur de ne pas générer d'en-tête ETag. Lorsqu'un serveur ignore la valeur de no-etag et génère tout de même un en-tête ETag, ce dernier sera respecté.
on
Les en-têtes ETag existants seront respectés, et ceux générés par le serveur seront ajoutés à la réponse.

Directive SSILastModified

Description: | Définit si des en-têtes Last-Modified sont générés par le serveur.
Syntaxe: | SSILastModified on|off
Défaut: | SSILastModified off
Contexte: | répertoire, .htaccess
Statut: | Base
Module: | mod_include
Compatibilité: | Disponible à partir de la version 2.2.15 du serveur HTTP Apache.

Dans le cas général, un fichier filtré par mod_include peut contenir des éléments soit générés dynamiquement, soit éventuellement modifiés indépendemment du fichier original. En conséquence, l'en-tête Last-Modified est supprimé par défaut de la réponse.

La directive SSILastModified permet de modifier ce comportement en faisant en sorte que l'en-tête Last-Modified soit respecté s'il est déjà présent, ou défini dans le cas contraire. On peut aussi l'utiliser pour la mise en cache de la sortie. La directive SSILastModified peut prendre une des valeurs suivantes :

off
L'en-tête Last-Modified sera supprimé des réponses, à moins que la directive XBitHack ne soit définie à full comme décrit plus loin.
on
L'en-tête Last-Modified sera respecté s'il est déjà présent, et ajouté à la réponse si cette dernière est un fichier et si l'en-tête est manquant. La directive SSILastModified l'emporte sur la directive XBitHack.

Directive SSILegacyExprParser

Description: | Active le mode de compatibilité pour les expressions conditionnelles.
Syntaxe: | SSILegacyExprParser on|off
Défaut: | SSILegacyExprParser off
Contexte: | répertoire, .htaccess
Statut: | Base
Module: | mod_include
Compatibilité: | Disponible à partir de la version 2.3.13.

Depuis la version 2.3.13, mod_include a adopté la nouvelle syntaxe ap_expr pour ses expressions conditionnelles dans les éléments de contrôle de flux #if. Cette directive permet de réactiver l'ancienne syntaxe qui est compatible avec les versions 2.2.x et antérieures d'Apache HTTPD.

Directive SSIStartTag

Description: | Chaîne qui marque le début d'un élément include
Syntaxe: | SSIStartTag tag
Défaut: | SSIStartTag "<!--#"
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_include

Cette directive permet de modifier la chaîne que mod_include interprète comme le début d'un élément include.

Cette option peut vous être utile si vous avez deux serveurs qui interprètent un fichier avec des commandes différentes (et éventuellement à des moments différents).

SSIStartTag "<%"
SSIEndTag   "%>"

Avec l'exemple ci-dessus, qui définit aussi une directive SSIEndTag, vous pourrez inscrire des directives SSI comme dans l'exemple suivant :

Directives SSI avec marques de début et de fin personnalisées

<%printenv %>

Voir aussi

  • SSIEndTag

Directive SSITimeFormat

Description: | Configuration du format d'affichage des dates
Syntaxe: | SSITimeFormat chaîne de formatage
Défaut: | SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Base
Module: | mod_include

Cette directive permet de modifier le format d'affichage des variables d'environnement DATE. La chaîne de formatage est identique à celle de la fonction strftime(3) de la bibliothèque C standard.

Cette directive a le même effet que l'élément <!--#config timefmt=chaîne de formatage -->.

SSITimeFormat "%R, %B %d, %Y"

Avec l'exemple ci-dessus, les dates seront affichées dans le style "22:26, June 14, 2002".

Directive SSIUndefinedEcho

Description: | Chaîne à afficher lorsqu'on tente d'extraire le contenu d'une variable non définie
Syntaxe: | SSIUndefinedEcho chaîne
Défaut: | SSIUndefinedEcho "(none)"
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Base
Module: | mod_include

Cette directive permet de modifier la chaîne affichée par mod_include lorsqu'on tente d'extraire le contenu d'une variable non définie.

SSIUndefinedEcho "<!-- nondef -->"

Directive XBitHack

Description: | Interprète les directives SSI dans les fichiers dont le bit d'exécution est positionné
Syntaxe: | XBitHack on|off|full
Défaut: | XBitHack off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_include

La directive XBitHack permet de contrôler l'interprétation des documents html standards. Elle n'affecte que les fichiers dont le type MIME est text/html. XBitHack peut prendre les valeurs suivantes :

off
Aucun traitement particulier pour les fichiers exécutables.
on
Tout fichier text/html dont le bit d'exécution est positionné pour le propriétaire sera traité en tant que document html interprété par le serveur.
full
Identique à on, avec test du bit d'exécution pour le groupe. Si ce dernier est positionné, la date de dernière modification du fichier renvoyé est définie à la date de dernière modification du fichier. Dans le cas contraire, aucune date de dernière modification n'est renvoyée. Le positionnement de ce bit permet aux clients et aux mandataires de gérer la mise en cache du résultat de la requête.

Note

Il est recommandé de n'utiliser l'option full que dans le cas où vous êtes certain que le bit d'exécution du groupe est non positionné pour les scripts SSI qui pourraient effectuer l'#include d'un programme CGI ou bien produire des sorties différentes à chaque accès (ou seraient susceptibles d'être modifiées au cours des requêtes ultérieures).

Lorsqu'elle est définie à on, la directive SSILastModified l'emporte sur la directive XBitHack.


mod_info - Serveur Apache HTTP Version 2.4

Module Apache mod_info

Description: | Affiche une présentation complète de la configuration du serveur
Statut: | Extension
Identificateur de Module: | info_module
Fichier Source: | mod_info.c

Sommaire

Pour activer mod_info, ajoutez les lignes suivantes à votre fichier httpd.conf.

<Location "/server-info">
    SetHandler server-info
</Location>

Il est recommandé d'utiliser mod_authz_host à l'intérieur de la section <Location> afin de restreindre l'accès aux informations de configuration de votre serveur :

<Location "/server-info">
    SetHandler server-info
    Require host example.com
</Location>

Une fois cette configuration effectuée, les informations du serveur sont disponibles à l'adresse http://votre-serveur.com/infos-serveur.

Problèmes liés à la sécurité

Une fois mod_info chargé dans le serveur, sa fonctionnalité de gestionnaire est disponible dans tous les fichiers de configuration, y compris les fichiers de configuration des répertoires (par exemple .htaccess). Ceci peut avoir des répercutions en matière de sécurité pour votre site.

En particulier, l'utilisation de ce module peut conduire à la divulgation d'informations sensibles à partir des directives de configuration d'autres modules Apache comme des chemins systèmes, des couples nom d'utilisateur/mot de passe, des noms de bases de données, etc... C'est pourquoi ce module ne doit être utilisé que dans un environnement sous contrôle et toujours avec les plus grandes précautions.

Il est recommandé d'utiliser mod_authz_host pour restreindre l'accès aux informations de configuration de votre serveur.

Contrôle d'accès

<Location "/server-info">
    SetHandler server-info
    # Autorisation d'accès depuis le serveur lui-même
    Require ip 127.0.0.1

    # Autorisation d'accès depuis une station de travail du réseau
# local
    Require ip 192.168.1.17
</Location>

Filtrage des informations affichées

Par défaut, les informations affichées comprennent une liste de tous les modules activés, et pour chaque module, une description des directives qu'il accepte, les branchements (hooks) qu'il implémente, ainsi que les directives concernées dans la configuration courante.

Il est possible d'afficher d'autres vues de la configuration en ajoutant un argument à la requête infos-serveur. Par exemple, http://votre-serveur.com/infos-serveur?config affichera toutes les directives de configuration.

?<module-name>
Uniquement les informations relatives au module spécifié
?config
Uniquement les directives de configuration, non triées par module
?hooks
Uniquement la liste des branchements (hooks) auxquels le module est attaché
?list
Une simple liste des modules activés
?server
Uniquement des informations de base sur le serveur
?providers
Liste des fournisseurs disponibles sur votre serveur

Affichage de la configuration au démarrage

Si la directive de configuration define -DDUMP_CONFIG est utilisée, mod_info va envoyer la configuration préinterprétée vers stdout au cours du démarrage du serveur.

httpd -DDUMP_CONFIG -k start

"Préinterprétée" signifie que les directives telles que <IfDefine> et <IfModule> sont évaluées et les variables d'environnement remplacées par leurs valeurs. Cela ne représente cependant pas la configuration définitive. En particulier, les fusions ou écrasementsde définitions en cas de directives multiples ne sont pas représentés.

Le résultat est équivalent à celui de la requête ?config.

Limitations connues

mod_info tire ses informations de la configuration interprétée, et non du fichier de configuration original. La manière dont l'arbre de configuration interprété est créé induit quelques limitations :

  • Les directives qui sont traitées immédiatement sans être enregistrées dans l'arbre de configuration interprété ne sont pas prises en compte. Celles-ci comprennent ServerRoot, LoadModule et LoadFile.
  • Les directives qui contrôlent le fichier de configuration lui-même, comme Include, <IfModule> et <IfDefine> ne sont pas prises en compte, mais les directives de configuration incluses le sont.
  • Les commentaires ne sont pas pris en compte (Ce qui peut être considéré comme une fonctionnalité).
  • Les directives de configuration des fichiers .htaccess ne sont pas prises en compte (car elles ne font pas partie de la configuration permanente du serveur).
  • Les directives de conteneur comme <Directory> sont affichées normalement, mais mod_info est incapable de déterminer le numéro de ligne de la balise fermante </Directory>.
  • Les directives générées par des modules tiers comme mod_perl peuvent ne pas être prises en compte.

Directive AddModuleInfo

Description: | Ajoute des données supplémentaires aux informations de module affichées par le gestionnaire server-info
Syntaxe: | AddModuleInfo nom-module chaîne
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_info

Cette directive permet d'afficher le contenu de chaîne en tant qu'Information supplémentaire interprétée en HTML pour le module nom-module. Exemple :

AddModuleInfo mod_deflate.c 'See <a \
    href="http://httpd.apache.org/docs/2.4/mod/mod_deflate.html">\
    http://httpd.apache.org/docs/2.4/mod/mod_deflate.html</a>'


mod_isapi - Serveur Apache HTTP Version 2.4

Module Apache mod_isapi

Description: | Extensions ISAPI dans Apache pour Windows
Statut: | Base
Identificateur de Module: | isapi_module
Fichier Source: | mod_isapi.c
Compatibilité: | Win32 only

Sommaire

Ce module implémente l'API des extensions du Serveur Internet. Il permet à Apache pour Windows de servir les extensions du Serveur Internet (par exemple les modules .dll ISAPI), compte tenu des restrictions spécifiées.

Les modules d'extension ISAPI (fichiers .dll) sont des modules tiers. Leur auteur n'est pas le Groupe Apache, et nous n'assurons donc pas leur support. Veuillez contacter directement l'auteur d'ISAPI si vous rencontrez des problèmes à l'exécution d'une extension ISAPI. Merci de ne pas soumettre ce genre de problème dans les listes d'Apache ou dans les pages de rapports de bogues.

Utilisation

Dans le fichier de configuration du serveur, utilisez la directive AddHandler pour associer les fichiers ISAPI au gestionnaire isapi-handler à l'aide de l'extension de leur nom de fichier. Pour faire en sorte que tout fichier .dll soit traité en tant qu'extension ISAPI, éditez le fichier httpd.conf et ajoutez les lignes suivantes :

AddHandler isapi-handler .dll
Dans les versions plus anciennes du serveur Apache, le nom du gestionnaire était isapi-isa au lieu de isapi-handler. Depuis les versions de développement 2.3 du serveur Apache, isapi-isa n'est plus valide, et vous devrez éventuellement modifier votre configuration pour utiliser isapi-handler à la place.

Le serveur Apache ne propose aucun moyen de conserver en mémoire un module chargé. Vous pouvez cependant précharger et garder un module spécifique en mémoire en utilisant la syntaxe suivante dans votre httpd.conf :

ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll

Que vous ayez ou non préchargé une extension ISAPI, ces dernières sont toutes soumises au mêmes restrictions et possèdent les mêmes permissions que les scripts CGI. En d'autres termes, Options ExecCGI doit être défini pour le répertoire qui contient le fichier .dll ISAPI.

Reportez-vous aux Notes additionnelles et au Journal du programmeur pour plus de détails et une clarification à propos du support spécifique ISAPI fourni par le module mod_isapi.

Notes additionnelles

L'implémentation ISAPI d'Apache se conforme à toutes les spécifications ISAPI 2.0, à l'exception de certaines extensions "spécifiques Microsoft" utilisant des entrées/sorties asynchrones. Le modèle des entrées/sorties d'Apache ne permet pas l'écriture et la lecture asynchrone de la manière dont ISAPI pourrait le faire. Si une extension tente d'utiliser des fonctionnalités non supportées, comme les entrées/sorties asynchrones, un message est enregistré dans le journal des erreurs afin d'aider au débogage. Comme ces messages peuvent devenir envahissants, la directive ISAPILogNotSupported Off permet de filter ce bruit de fond.

Si aucune option de configuration particulière n'est spécifiée, certains serveurs, comme Microsoft IIS, chargent l'extension ISAPI dans le serveur et la conservent en mémoire jusqu'à ce que l'utilisation de cette dernière devienne trop élevée. Apache, par contre, charge et décharge réellement l'extension ISAPI chaque fois qu'elle est invoquée, si la directive ISAPICacheFile n'a pas été spécifiée. Ce n'est pas très performant, mais le modèle de mémoire d'Apache fait que cette méthode est la plus efficace. De nombreux modules ISAPI présentent des incompatibilités subtiles avec le serveur Apache, et le déchargement de ces modules permet d'assurer la stabilité du serveur.

En outre, gardez à l'esprit que si Apache supporte les extensions ISAPI, il ne supporte pas les filtres ISAPI. Le support des filtres sera peut-être ajouté dans le futur, mais n'a pas encore été planifié.

Journal du programmeur

Si vous écrivez des modules mod_isapi Apache 2.0, vous devez limiter vos appels à ServerSupportFunction aux directives suivantes :

HSE_REQ_SEND_URL_REDIRECT_RESP
Redirige l'utilisateur vers une autre adresse.
Il doit s'agir d'une URL pleinement qualifiée (comme http://serveur/chemin).
HSE_REQ_SEND_URL
Redirige l'utilisateur vers une autre adresse.
Ce ne doit pas être une URL pleinement qualifiée ; la mention du protocole ou du nom du serveur n'est pas autorisée (par exemple, utilisez simplement /chemin).
La redirection n'est pas assurée par le navigateur mais par le serveur lui-même.

Avertissement

Dans sa documentation récente, Microsoft semble avoir abandonné la distinction entre les deux fonctions HSE_REQ_SEND_URL. Apache, quant à lui, continue de les traiter comme deux fonctions distinctes avec des contraintes et des comportements spécifiques.

HSE_REQ_SEND_RESPONSE_HEADER
Apache accepte un corps de réponse après l'en-tête s'il se situe après la ligne vide (deux caractères newline consécutifs) dans la chaîne des arguments d'en-têtes. Ce corps ne doit pas contenir de caractères NULL, car l'argument des en-têtes est lui-même terminé par un caractère NULL.
HSE_REQ_DONE_WITH_SESSION
Apache considère ceci comme sans objet, car la session est fermée lorsque l'extension ISAPI termine son traitement.
HSE_REQ_MAP_URL_TO_PATH
Apache va traduire un nom virtuel en nom physique.
HSE_APPEND_LOG_PARAMETER
Ce paramètre peut intervenir dans un de ces journaux :
  • dans le composant \"%{isapi-parameter}n\" d'une directive CustomLog
  • dans le composant %q avec la directive ISAPIAppendLogToQuery On
  • dans le journal des erreurs avec la directive ISAPIAppendLogToErrors On

La première option, le composant %{isapi-parameter}n, est préférable et toujours disponible.

HSE_REQ_IS_KEEP_CONN
retourne le statut négocié Keep-Alive.
HSE_REQ_SEND_RESPONSE_HEADER_EX
se comportera comme indiqué dans le documentation, bien que le drapeau fKeepConn soit ignoré.
HSE_REQ_IS_CONNECTED
renverra faux si la requête a été abandonnée.

Apache renvoie FALSE pour tout appel non supporté à ServerSupportFunction, et GetLastError renverra la valeur ERROR_INVALID_PARAMETER.

ReadClient extrait la partie du corps de la requête qui dépasse le tampon initial (défini par la directive ISAPIReadAheadBuffer). En fonction de la définition de la directive ISAPIReadAheadBuffer (nombre d'octets à mettre dans le tampon avant d'appeler le gestionnaire ISAPI), les requêtes courtes sont envoyées en entier à l'extension lorsque celle-ci est invoquée. Si la taille de la requête est trop importante, l'extension ISAPI doit faire appel à ReadClient pour extraire la totalité du corps de la requête.

WriteClient est supporté, mais seulement avec le drapeau HSE_IO_SYNC ou le drapeau "aucune option" (valeur 0). Toute autre requête WriteClient sera rejetée avec une valeur de retour FALSE, et GetLastError renverra la valeur ERROR_INVALID_PARAMETER

GetServerVariable est supporté, bien que les variables étendues de serveur n'existent pas (comme défini par d'autres serveurs). Toutes les variables d'environnement CGI usuelles d'Apache sont disponibles à partir de GetServerVariable, ainsi que les valeurs ALL_HTTP et ALL_RAW.

Depuis httpd 2.0, mod_isapi propose des fonctionnalités supplémentaires introduites dans les versions actualisées de la spécification ISAPI, ainsi qu'une émulation limitée des entrées/sorties asynchrones et la sémantique TransmitFile. Apache httpd supporte aussi le préchargement des .dlls ISAPI à des fins de performances.

Directive ISAPIAppendLogToErrors

Description: | Enregistrement des requêtes HSE_APPEND_LOG_PARAMETER de la part des extensions ISAPI dans le journal des erreurs
Syntaxe: | ISAPIAppendLogToErrors on|off
Défaut: | ISAPIAppendLogToErrors off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet d'enregistrer les requêtes HSE_APPEND_LOG_PARAMETER de la part des extensions ISAPI dans le journal des erreurs.

Directive ISAPIAppendLogToQuery

Description: | Enregistre les requêtes HSE_APPEND_LOG_PARAMETER de la part des extensions ISAPI dans la partie arguments de la requête
Syntaxe: | ISAPIAppendLogToQuery on|off
Défaut: | ISAPIAppendLogToQuery on
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet d'enregistrer les requêtes HSE_APPEND_LOG_PARAMETER de la part des extensions ISAPI dans la partie arguments de la requête (ajouté au composant %q de la directive CustomLog).

Directive ISAPICacheFile

Description: | Fichiers .dll ISAPI devant être chargés au démarrage
Syntaxe: | ISAPICacheFile chemin-fichier [chemin-fichier] ...
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_isapi

Cette directive permet de spécifier une liste, séparés par des espaces, de noms de fichiers devant être chargés au démarrage du serveur Apache, et rester en mémoire jusqu'à l'arrêt du serveur. Cette directive peut être répétée pour chaque fichier .dll ISAPI souhaité. Le chemin complet du fichier doit être spécifié. Si le chemin n'est pas absolu, il sera considéré comme relatif au répertoire défini par la directive ServerRoot.

Directive ISAPIFakeAsync

Description: | Emulation du support des entrées/sorties asynchrones pour les appels ISAPI
Syntaxe: | ISAPIFakeAsync on|off
Défaut: | ISAPIFakeAsync off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_isapi

Lorsquelle est définie à "on", cette directive permet d'émuler le support des entrées/sorties asynchrones pour les appels ISAPI.

Directive ISAPILogNotSupported

Description: | Journalisation des demandes de fonctionnalités non supportées de la part des extensions ISAPI
Syntaxe: | ISAPILogNotSupported on|off
Défaut: | ISAPILogNotSupported off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet d'enregistrer dans le journal des erreurs toutes les demandes de fonctionnalités non supportées de la part des extensions ISAPI. Ceci peut aider les administrateurs à décortiquer certains problèmes. Lorsqu'elle a été définie à "on" et si tous les modules ISAPI fonctionnent, elle peut être redéfinie à "off".

Directive ISAPIReadAheadBuffer

Description: | Taille du tampon de lecture anticipée envoyé aux extensions ISAPI
Syntaxe: | ISAPIReadAheadBuffer taille
Défaut: | ISAPIReadAheadBuffer 49152
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_isapi

Cette directive permet de définir la taille maximale du tampon de lecture anticipée envoyé aux extensions ISAPI lorsqu'elles sont initialement invoquées. Toute donnée restante doit être extraite en faisant appel à ReadClient ; certaines extensions ISAPI peuvent ne pas supporter la fonction ReadClient. Pour plus de détails, veuillez vous adresser à l'auteur de l'extension ISAPI.


mod_lbmethod_bybusyness - Serveur Apache HTTP Version 2.4

Module Apache mod_lbmethod_bybusyness

Description: | Algorithme de planification avec répartition de charge de l'attribution des requêtes en attente pour le module mod_proxy_balancer
Statut: | Extension
Identificateur de Module: | lbmethod_bybusyness_module
Fichier Source: | mod_lbmethod_bybusyness.c
Compatibilité: | Dissocié de mod_proxy_balancer depuis la version 2.3

Sommaire

Ce module ne fournit pas lui-même de directive de configuration. Il nécessite les services de mod_proxy_balancer, et fournit la méthode de répartition de charge bybusyness.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • mod_proxy_balancer

Algorithme d'attribution des requêtes en attente

Activé via lbmethod=bybusyness, ce planificateur surveille le nombre de requêtes assignées à chaque processus worker à l'instant présent. Une nouvelle requête est automatiquement assignée au processus worker auquel est assigné le plus petit nombre de requêtes. Ceci s'avère utile dans le cas où les processus worker mettent en file d'attente les requêtes entrantes indépendamment d'Apache, et permet de s'assurer que la longueur des files reste raisonnable, et qu'une requête est toujours assignée au processus worker qui sera à même de la servir le plus rapidement et avec une latence réduite.

Si plusieurs processus worker s'avèrent les moins chargés, le choix d'un de ces derniers est effectué à partir des statistiques (et des estimations de charges) qu'utilise la méthode de décompte des requêtes. Au fil du temps, la distribution des tâches finit par ressembler à celle de byrequests (tel qu'implémenté par mod_lbmethod_byrequests).


mod_lbmethod_byrequests - Serveur Apache HTTP Version 2.4

Module Apache mod_lbmethod_byrequests

Description: | Algorithme de planification avec répartition de charge du traitement des requêtes pour le module mod_proxy_balancer
Statut: | Extension
Identificateur de Module: | lbmethod_byrequests_module
Fichier Source: | mod_lbmethod_byrequests.c
Compatibilité: | Dissocié de mod_proxy_balancer dans la version 2.3

Sommaire

Ce module ne fournit pas lui-même de directive de configuration. Il nécessite les services de mod_proxy_balancer, et fournit la méthode de répartition de charge byrequests.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • mod_proxy_balancer

Algorithme d'attribution des requêtes

Activé via lbmethod=byrequests, ce planificateur à été conçu dans le but de distribuer les requêtes à tous les processus worker afin qu'ils traitent tous le nombre de requêtes pour lequel ils ont été configurés. Il fonctionne de la manière suivante :

lbfactor correspond à la quantité de travail que nous attendons de ce processus worker, ou en d'autres termes son quota de travail. C'est une valeur normalisée représentant leur part du travail à accomplir.

lbstatus représente combien il est urgent que ce processus worker travaille pour remplir son quota de travail.

Le worker est un membre du dispositif de répartition de charge, en général un serveur distant traitant un des protocoles supportés.

On distribue à chaque processus worker son quota de travail, puis on regarde celui qui a le plus besoin de travailler (le plus grand lbstatus). Ce processus est alors sélectionné pour travailler, et son lbstatus diminué de l'ensemble des quotas de travail que nous avons distribués à tous les processus. La somme de tous les lbstatus n'est ainsi pas modifiée, et nous pouvons distribuer les requêtes selon nos souhaits.

Si certains processus workers sont désactivés, les autres feront l'objet d'une planification normale.

for each worker in workers
    worker lbstatus += worker lbfactor
    total factor    += worker lbfactor
    if worker lbstatus > candidate lbstatus
        candidate = worker

candidate lbstatus -= total factor

Si un répartiteur de charge est configuré comme suit :

worker | a | b | c | d
lbfactor | 25 | 25 | 25 | 25
lbstatus | 0 | 0 | 0 | 0

Et si b est désactivé, la planification suivante est mise en oeuvre :

worker | a | b | c | d
lbstatus | -50 | 0 | 25 | 25
lbstatus | -25 | 0 | -25 | 50
lbstatus | 0 | 0 | 0 | 0
(repeat)

C'est à dire la chronologie suivante : a c d a c d a c d ... Veuillez noter que :

worker | a | b | c | d
lbfactor | 25 | 25 | 25 | 25

A le même effet que :

worker | a | b | c | d
lbfactor | 1 | 1 | 1 | 1

Ceci est dû au fait que toutes les valeurs de lbfactor sont normalisées et évaluées en fonction des autres. Avec :

worker | a | b | c
lbfactor | 1 | 4 | 1

le processus b va, en moyenne, se voir assigner 4 fois plus de requêtes que a et c.

La configuration suivante, asymétrique, fonctionne comme on peut s'y attendre :

worker | a | b
lbfactor | 70 | 30
lbstatus | -30 | 30
lbstatus | 40 | -40
lbstatus | 10 | -10
lbstatus | -20 | 20
lbstatus | -50 | 50
lbstatus | 20 | -20
lbstatus | -10 | 10
lbstatus | -40 | 40
lbstatus | 30 | -30
lbstatus | 0 | 0
(repeat)

Après 10 distributions, la planification se répète et 7 a sont sélectionnés avec 3 b intercalés.


mod_lbmethod_bytraffic - Serveur Apache HTTP Version 2.4

Module Apache mod_lbmethod_bytraffic

Description: | Algorithme de planification avec répartition de charge en fonction d'un niveau de trafic pour le module mod_proxy_balancer
Statut: | Extension
Identificateur de Module: | lbmethod_bytraffic_module
Fichier Source: | mod_lbmethod_bytraffic.c
Compatibilité: | Dissocié de mod_proxy_balancer depuis la version 2.3

Sommaire

Ce module ne fournit pas lui-même de directive de configuration. Il nécessite les services de mod_proxy_balancer, et fournit la méthode de répartition de charge bytraffic.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • mod_proxy_balancer

Algorithme de répartition en fonction d'un certain trafic

Activé via lbmethod=bytraffic, l'idée directrice de ce planificateur est similaire à celle de la méthode reposant sur le nombre de requêtes, avec les différences suivantes :

lbfactor représente la quantité de trafic, en octets, que nous voulons voir traitée par le processus. Il s'agit là aussi d'une valeur normalisée représentant la part de travail à effectuer par le processus, mais au lieu de se baser sur un nombre de requêtes, on prend en compte la quantité de trafic que ce processus a traité.

Si un répartiteur est configuré comme suit :

worker | a | b | c
lbfactor | 1 | 2 | 1

Cela signifie que nous souhaitons que b traite 2 fois plus d'octets que a ou c. Cela n'entraîne pas nécessairement que b va traiter deux fois plus de requêtes, mais qu'il va traiter deux fois plus de trafic en termes d'entrées/sorties. A cet effet, les tailles de la requête et de sa réponse assocciée sont prises en compte par l'algorithme de sélection et d'évaluation du trafic.

Note : les octets en entrée sont évalués avec la même pondération que les octets en sortie.


mod_lbmethod_heartbeat - Serveur Apache HTTP Version 2.4

Module Apache mod_lbmethod_heartbeat

Description: | Algorithme d'ordonnancement de répartition de charge pour mod_proxy_balancer basé sur le comptage de trafic Heartbeat
Statut: | Expérimental
Identificateur de Module: | lbmethod_heartbeat_module
Fichier Source: | mod_lbmethod_heartbeat.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

lbmethod=heartbeat utilise les services du module mod_heartmonitor pour répartir la charge entre les serveurs d'origine qui fournissent des données heartbeat via le module mod_heartbeat.

Son algorithme de répartition de charge favorise les serveurs dont la capacité de traitement moyenne répartie dans le temps est la plus importante, mais il ne sélectionne pas forcément le serveur qui présente la disponibilité instantanée la plus importante. Les serveurs qui ne possèdent aucun client actif sont pénalisés, car ils sont considérés comme non entièrement initialisés.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • mod_proxy_balancer
  • mod_heartbeat
  • mod_heartmonitor

Directive HeartbeatStorage

Description: | Indique le chemin permettant de lire les données heartbeat
Syntaxe: | HeartbeatStorage chemin-fichier
Défaut: | HeartbeatStorage logs/hb.dat
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_lbmethod_heartbeat

La directive HeartbeatStorage permet de spécifier le chemin d'accès aux données heartbeat. Ce fichier texte n'est utilisé que si le module mod_slotmem_shm n'est pas chargé.


mod_ldap - Serveur Apache HTTP Version 2.4

Module Apache mod_ldap

Description: | Conservation des connexions LDAP et services de mise en cache du résultat à destination des autres modules LDAP
Statut: | Extension
Identificateur de Module: | ldap_module
Fichier Source: | util_ldap.c

Sommaire

Ce module a été conçu dans le but d'améliorer les performances des sites web s'appuyant sur des connexions en arrière-plan vers des serveurs LDAP. Il ajoute aux fonctions fournies par les bibliothèques standards LDAP la conservation des connexions LDAP ainsi qu'un cache LDAP partagé en mémoire.

Pour activer ce module, le support LDAP doit être compilé dans apr-util. Pour ce faire, on ajoute l'option --with-ldap au script configure lorsqu'on construit Apache.

Le support SSL/TLS est conditionné par le kit de développement LDAP qui a été lié à APR. Au moment où ces lignes sont écrites, APR-util supporte OpenLDAP SDK (version 2.x ou supérieure), Novell LDAP SDK, Mozilla LDAP SDK, le SDK LDAP Solaris natif (basé sur Mozilla) ou le SDK LDAP Microsoft natif. Voir le site web APR pour plus de détails.

Exemple de configuration

Ce qui suit est un exemple de configuration qui utilise mod_ldap pour améliorer les performances de l'authentification HTTP de base fournie par mod_authnz_ldap.

# Active la conservation des connexions LDAP et le cache partagé en
# mémoire. Active le gestionnaire de statut du cache LDAP.
# Nécessite le chargement de mod_ldap et de mod_authnz_ldap.
# Remplacez "votre-domaine.example.com" par le nom de votre
# domaine.

LDAPSharedCacheSize 500000
LDAPCacheEntries 1024
LDAPCacheTTL 600
LDAPOpCacheEntries 1024
LDAPOpCacheTTL 600

<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>

Conservation des connexions LDAP

Les connexions LDAP sont conservées de requête en requête. Ceci permet de rester connecté et identifié au serveur LDAP, ce dernier étant ainsi prêt pour la prochaine requête, sans avoir à se déconnecter, reconnecter et réidentifier. Le gain en performances est similaire à celui des connexions persistantes (keepalives) HTTP.

Sur un serveur très sollicité, il est possible que de nombreuses requêtes tentent d'accéder simultanément à la même connexion au serveur LDAP. Lorsqu'une connexion LDAP est utilisée, Apache en crée une deuxième en parallèle à la première, ce qui permet d'éviter que le système de conservation des connexions ne devienne un goulot d'étranglement.

Il n'est pas nécessaire d'activer explicitement la conservation des connexions dans la configuration d'Apache. Tout module utilisant le module ldap pour accéder aux services LDAP partagera le jeu de connexions.

Les connexions LDAP peuvent garder la trace des données d'identification du client ldap utilisées pour l'identification auprès du serveur LDAP. Ces données peuvent être fournies aux serveurs LDAP qui ne permettent pas les connexions anonymes au cours lors des tentatives de sauts vers des serveurs alternatifs. Pour contrôler cette fonctionnalité, voir les directives LDAPReferrals et LDAPReferralHopLimit. Cette fonctionnalité est activée par défaut.

Cache LDAP

Pour améliorer les performances, mod_ldap met en oeuvre une stratégie de mise en cache agressive visant à minimiser le nombre de fois que le serveur LDAP doit être contacté. La mise en cache peut facilement doubler et même tripler le débit d'Apache lorsqu'il sert des pages protégées par mod_authnz_ldap. De plus, le serveur LDAP verra lui-même sa charge sensiblement diminuée.

mod_ldap supporte deux types de mise en cache LDAP : un cache recherche/identification durant la phase de recherche/identification et deux caches d'opérations durant la phase de comparaison. Chaque URL LDAP utilisée par le serveur a son propre jeu d'instances dans ces trois caches.

Le cache recherche/identification

Les processus de recherche et d'identification sont les opérations LDAP les plus consommatrices en temps, en particulier si l'annuaire est de grande taille. Le cache de recherche/identification met en cache toutes les recherches qui ont abouti à une identification positive. Les résultats négatifs (c'est à dire les recherches sans succès, ou les recherches qui n'ont pas abouti à une identification positive) ne sont pas mis en cache. La raison de cette décision réside dans le fait que les connexions avec des données d'identification invalides ne représentent qu'un faible pourcentage du nombre total de connexions, et ainsi, le fait de ne pas mettre en cache les données d'identification invalides réduira d'autant la taille du cache.

mod_ldap met en cache le nom d'utilisateur, le DN extrait, le mot de passe utilisé pour l'identification, ainsi que l'heure de l'identification. Chaque fois qu'une nouvelle connexion est initialisée avec le même nom d'utilisateur, mod_ldap compare le mot de passe de la nouvelle connexion avec le mot de passe enregistré dans le cache. Si les mots de passe correspondent, et si l'entrée du cache n'est pas trop ancienne, mod_ldap court-circuite la phase de recherche/identification.

Le cache de recherche/identification est contrôlé par les directives LDAPCacheEntries et LDAPCacheTTL.

Les caches d'opérations

Au cours des opérations de comparaison d'attributs et de noms distinctifs (DN), mod_ldap utilise deux caches d'opérations pour mettre en cache les opérations de comparaison. Le premier cache de comparaison sert à mettre en cache les résultats de comparaisons effectuées pour vérifier l'appartenance à un groupe LDAP. Le second cache de comparaison sert à mettre en cache les résultats de comparaisons entre DNs.

Notez que, lorsque l'appartenance à un groupe est vérifiée, toute comparaison de sous-groupes est mise en cache afin d'accélérer les comparaisons de sous-groupes ultérieures.

Le comportement de ces deux caches est contrôlé par les directives LDAPOpCacheEntries et LDAPOpCacheTTL.

Superviser le cache

mod_ldap possède un gestionnaire de contenu qui permet aux administrateurs de superviser les performances du cache. Le nom du gestionnaire de contenu est ldap-status, et on peut utiliser les directives suivantes pour accéder aux informations du cache de mod_ldap :

<Location "/server/cache-info">
    SetHandler ldap-status
</Location>

En se connectant à l'URL http://nom-serveur/infos-cache, l'administrateur peut obtenir un rapport sur le statut de chaque cache qu'utilise mod_ldap. Notez que si Apache ne supporte pas la mémoire partagée, chaque instance de httpd possèdera son propre cache, et chaque fois que l'URL sera rechargée, un résultat différent pourra être affiché, en fonction de l'instance de httpd qui traitera la requête.

Utiliser SSL/TLS

La possibilité de créer des connexions SSL et TLS avec un serveur LDAP est définie par les directives LDAPTrustedGlobalCert, LDAPTrustedClientCert et LDAPTrustedMode. Ces directives permettent de spécifier l'autorité de certification (CA), les certificats clients éventuels, ainsi que le type de chiffrement à utiliser pour la connexion (none, SSL ou TLS/STARTTLS).

# Etablissement d'une connexion SSL LDAP sur le port 636.
# Nécessite le chargement de mod_ldap et mod_authnz_ldap.
# Remplacez "votre-domaine.example.com" par le nom de votre
# domaine.

LDAPTrustedGlobalCert CA_DER "/certs/certfile.der"

<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>
# Etablissement d'une connexion TLS LDAP sur le port 389.
# Nécessite le chargement de mod_ldap et mod_authnz_ldap.
# Remplacez "votre-domaine.example.com" par le nom de votre
# domaine.

LDAPTrustedGlobalCert CA_DER "/certs/certfile.der"

<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=com?uid?one" TLS
    Require valid-user
</Location>

Certificats SSL/TLS

Les différents SDKs LDAP disposent de nombreuses méthodes pour définir et gérer les certificats des clients et des autorités de certification (CA).

Si vous avez l'intention d'utiliser SSL ou TLS, lisez cette section ATTENTIVEMENT de façon à bien comprendre les différences de configurations entre les différents SDKs LDAP supportés.

SDK Netscape/Mozilla/iPlanet

Les certificat de CA sont enregistrés dans un fichier nommé cert7.db. Le SDK ne dialoguera avec aucun serveur LDAP dont le certificat n'a pas été signé par une CA spécifiée dans ce fichier. Si des certificats clients sont requis, un fichier key3.db ainsi qu'un mot de passe optionnels peuvent être spécifiés. On peut aussi spécifier le fichier secmod si nécessaire. Ces fichiers sont du même format que celui utilisé par les navigateurs web Netscape Communicator ou Mozilla. Le moyen le plus simple pour obtenir ces fichiers consiste à les extraire de l'installation de votre navigateur.

Les certificats clients sont spécifiés pour chaque connexion en utilisant la directive LDAPTrustedClientCert et en se référant au certificat "nickname". On peut éventuellement spécifier un mot de passe pour déverrouiller la clé privée du certificat.

Le SDK supporte seulement SSL. Toute tentative d'utilisation de STARTTLS engendrera une erreur lors des tentatives de contacter le serveur LDAP pendant l'exécution.

# Spécifie un fichier de certificats de CA Netscape
LDAPTrustedGlobalCert CA_CERT7_DB "/certs/cert7.db"
# Spécifie un fichier key3db optionnel pour le support des
# certificats clients
LDAPTrustedGlobalCert CERT_KEY3_DB "/certs/key3.db"
# Spécifie le fichier secmod si nécessaire
LDAPTrustedGlobalCert CA_SECMOD "/certs/secmod"
<Location "/ldap-status">
    SetHandler ldap-status

    Require host yourdomain.example.com

    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    LDAPTrustedClientCert CERT_NICKNAME <nickname> [password]
    AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>

SDK Novell

Un ou plusieurs certificats de CA doivent être spécifiés pour que le SDK Novell fonctionne correctement. Ces certificats peuvent être spécifiés sous forme de fichiers au format binaire DER ou codés en Base64 (PEM).

Note: Les certificats clients sont spécifiés globalement plutôt qu'à chaque connexion, et doivent être spécifiés à l'aide de la directive LDAPTrustedGlobalCert comme ci-dessous. Définir des certificats clients via la directive LDAPTrustedClientCert engendrera une erreur qui sera journalisée, au moment de la tentative de connexion avec le serveur LDAP.

Le SDK supporte SSL et STARTTLS, le choix étant défini par le paramètre de la directive LDAPTrustedMode. Si une URL de type ldaps:// est spécifiée, le mode SSL est forcé, et l'emporte sur cette directive.

# Spécifie deux fichiers contenant des certificats de CA
LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
# Spécifie un fichier contenant des certificats clients
# ainsi qu'une clé
LDAPTrustedGlobalCert CERT_BASE64 "/certs/cert1.pem"
LDAPTrustedGlobalCert KEY_BASE64 "/certs/key1.pem" [password]
# N'utilisez pas cette directive, sous peine de provoquer
# une erreur
#LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"

SDK OpenLDAP

Un ou plusieurs certificats de CA doivent être spécifiés pour que le SDK OpenLDAP fonctionne correctement. Ces certificats peuvent être spécifiés sous forme de fichiers au format binaire DER ou codés en Base64 (PEM).

Les certificats clients sont spécifiés pour chaque connexion à l'aide de la directive LDAPTrustedClientCert.

La documentation du SDK prétend que SSL et STARTTLS sont supportés ; cependant, STARTTLS semble ne pas fonctionner avec toutes les versions du SDK. Le mode SSL/TLS peut être défini en utilisant le paramètre de la directive LDAPTrustedMode. Si une URL de type ldaps:// est spécifiée, le mode SSL est forcé. La documentation OpenLDAP indique que le support SSL (ldaps://) tend à être remplacé par TLS, bien que le mode SSL fonctionne toujours.

# Spécifie deux fichiers contenant des certificats de CA
LDAPTrustedGlobalCert CA_DER "/certs/cacert1.der"
LDAPTrustedGlobalCert CA_BASE64 "/certs/cacert2.pem"
<Location /ldap-status>
    SetHandler ldap-status

    Require host yourdomain.example.com

    LDAPTrustedClientCert CERT_BASE64 "/certs/cert1.pem"
    LDAPTrustedClientCert KEY_BASE64 "/certs/key1.pem"
    # CA certs respecified due to per-directory client certs
    LDAPTrustedClientCert CA_DER "/certs/cacert1.der"
    LDAPTrustedClientCert CA_BASE64 "/certs/cacert2.pem"
    Satisfy any
    AuthType Basic
    AuthName "LDAP Protected"
    AuthBasicProvider ldap
    AuthLDAPURL "ldaps://127.0.0.1/dc=example,dc=com?uid?one"
    Require valid-user
</Location>

SDK Solaris

SSL/TLS pour les bibliothèques LDAP propres à Solaris n'est pas encore supporté. Si nécessaire, installez et utilisez plutôt les bibliothèques OpenLDAP.

SDK Microsoft

La configuration des certificats SSL/TLS pour les bibliothèques LDAP propres à Microsoft s'effectue à l'intérieur du registre système, et aucune directive de configuration n'est requise.

SSL et TLS sont tous deux supportés en utilisant des URLs de type ldaps://, ou en définissant la directive LDAPTrustedMode à cet effet.

Note: L'état du support des certificats clients n'est pas encore connu pour ce SDK.

Directive LDAPCacheEntries

Description: | Nombre maximum d'entrées dans le cache LDAP primaire
Syntaxe: | LDAPCacheEntries nombre
Défaut: | LDAPCacheEntries 1024
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier la taille maximale du cache LDAP primaire. Ce cache contient les résultats de recherche/identification positifs. Définissez-la à 0 pour désactiver la mise en cache des résultats de recherche/identification positifs. La taille par défaut est de 1024 recherches en cache.

Directive LDAPCacheTTL

Description: | Durée pendant laquelle les entrées du cache restent valides.
Syntaxe: | LDAPCacheTTL secondes
Défaut: | LDAPCacheTTL 600
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier la durée (en secondes) pendant laquelle une entrée du cache de recherche/identification reste valide. La valeur par défaut est de 600 secondes (10 minutes).

Directive LDAPConnectionPoolTTL

Description: | Désactive les connexions d'arrière-plan qui sont restées inactives trop longtemps au sein du jeu de connexions.
Syntaxe: | LDAPConnectionPoolTTL n
Défaut: | LDAPConnectionPoolTTL -1
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ldap
Compatibilité: | Disponible à partir de la version 2.3.12 du serveur HTTP Apache

Cette directive permet de spécifier la durée maximale, en secondes, pendant laquelle une connexion LDAP du jeu de connexions peut demeurer inactive, mais rester quand-même disponible pour une utilisation éventuelle. Le jeu de connexions est nettoyé au fur et à mesure des besoins, de manière non asynchrone.

Si cette directive est définie à 0, les connexions ne sont jamais sauvegardées dans le jeu de connexions d'arrière-plan. Avec la valeur par défaut -1, ou toute autre valeur négative, les connexions peuvent être réutilisées sans limite de durée.

Dans le but d'améliorer les performances, le temps de référence qu'utilise cette directive correspond au moment où la connexion LDAP est enregistrée ou remise dans le jeu de connexions, et non au moment du dernier échange réussi avec le serveur LDAP.

La version 2.4.10 a introduit de nouvelles mesures permettant d'éviter une augmentation excessive du temps de référence due à des correspondances positives dans le cache ou des requêtes lentes. A cet effet, le temps de référence n'est pas réactualisé si aucune connexion LDAP d'arrière-plan n'est requise ; d'autre part, le temps de référence se base sur le moment où la requête HTTP est reçue, et non sur le moment où la requête a été traitée.

Cette durée de vie s'exprime par défaut en secondes, mais il est possible d'utiliser d'autres unités en ajoutant un suffixe : millisecondes (ms), minutes (min), ou heures (h).

Directive LDAPConnectionTimeout

Description: | Spécifie le délai d'attente en secondes de la socket de connexion
Syntaxe: | LDAPConnectionTimeout secondes
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive configure l'option LDAP_OPT_NETWORK_TIMEOUT (ou LDAP_OPT_CONNECT_TIMEOUT) dans la bibliothèque client LDAP sous-jacente, si elle est disponible. Cette valeur représente la durée pendant laquelle la bibliothèque client LDAP va attendre que le processus de connexion TCP au serveur LDAP soit achevé.

Si la connexion n'a pas réussi avant ce délai, une erreur sera renvoyée, ou la bibliothèque client LDAP tentera de se connecter à un second serveur LDAP, s'il en a été défini un (via une liste de noms d'hôtes séparés par des espaces dans la directive AuthLDAPURL).

La valeur par défaut est 10 secondes, si la bibliothèque client LDAP liée avec le serveur supporte l'option LDAP_OPT_NETWORK_TIMEOUT.

LDAPConnectionTimeout n'est disponible que si la bibliothèque client LDAP liée avec le serveur supporte l'option LDAP_OPT_NETWORK_TIMEOUT (ou LDAP_OPT_CONNECT_TIMEOUT), et le comportement final est entièrement dicté par la bibliothèque client LDAP.

Directive LDAPLibraryDebug

Description: | Active le débogage dans le SDK LDAP
Syntaxe: | LDAPLibraryDebug 7
Défaut: | disabled
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Active les options de débogage LDAP spécifiques au SDK, qui entraînent en général une journalisation d'informations verbeuses du SDK LDAP dans le journal principal des erreurs d'Apache. Les messages de traces en provenance du SDK LDAP fournissent des informations très détaillées qui peuvent s'avérer utiles lors du débogage des problèmes de connexion avec des serveurs LDAP d'arrière-plan.

Cette option n'est configurable que lorsque le serveur HTTP Apache est lié avec un SDK LDAP qui implémente LDAP_OPT_DEBUG ou LDAP_OPT_DEBUG_LEVEL, comme OpenLDAP (une valeur de 7 est verbeuse) ou Tivoli Directory Server (une valeur de 65535 est verbeuse).

Les informations journalisées peuvent contenir des données d'authentification en clair utilisées ou validées lors de l'authentification LDAP ; vous devez donc prendre soin de protéger et de purger le journal des erreurs lorsque cette directive est utilisée.

Directive LDAPOpCacheEntries

Description: | Nombre d'entrées utilisées pour mettre en cache les opérations de comparaison LDAP
Syntaxe: | LDAPOpCacheEntries nombre
Défaut: | LDAPOpCacheEntries 1024
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier le nombre d'entrées que mod_ldap va utiliser pour mettre en cache les opérations de comparaison LDAP. La valeur par défaut est de 1024 entrées. Si elle est définie à 0, la mise en cache des opérations de comparaison LDAP est désactivée.

Directive LDAPOpCacheTTL

Description: | Durée pendant laquelle les entrées du cache d'opérations restent valides
Syntaxe: | LDAPOpCacheTTL secondes
Défaut: | LDAPOpCacheTTL 600
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier la durée (en secondes) pendant laquelle les entrées du cache d'opérations restent valides. La valeur par défaut est de 600 secondes.

Directive LDAPReferralHopLimit

Description: | Le nombre maximum de redirections vers des serveurs alternatifs (referrals) avant l'abandon de la requête LDAP.
Syntaxe: | LDAPReferralHopLimit nombre
Défaut: | Dépend du SDK, en général entre 5 et 10
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ldap

Si elle est activée par la directive LDAPReferrals, cette directive permet de définir le nombre maximum de sauts vers des serveurs alternatifs (referrals) avant l'abandon de la requête LDAP.

L'ajustement de ce paramètre n'est pas commun à tous les SDKs LDAP.

Directive LDAPReferrals

Description: | Active la redirection vers des serveurs alternatifs au cours des requêtes vers le serveur LDAP.
Syntaxe: | LDAPReferrals On|Off|default
Défaut: | LDAPReferrals On
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ldap
Compatibilité: | Le paramètre default est disponible depuis la version 2.4.7 du serveur HTTP Apache.

Certains serveurs LDAP partagent leur annuaire en plusieurs domaines et utilisent le système des redirections (referrals) pour aiguiller un client lorsque les limites d'un domaine doivent être franchies. Ce processus est similaire à une redirection HTTP. Les bibliothèques client LDAP ne respectent pas forcément ces redirections par défaut. Cette directive permet de configurer explicitement les redirections LDAP dans le SDK sous-jacent.

La directive LDAPReferrals accepte les valeurs suivantes :

"on"

Avec la valeur "on", la prise en compte des redirections LDAP par le SDK sous-jacent est activée, la directive LDAPReferralHopLimit permet de surcharger la "hop limit" du SDK, et un "LDAP rebind callback" est enregistré.

"off"

Avec la valeur "off", la prise en compte des redirections LDAP par le SDK sous-jacent est complètement désactivée.

"default"

Avec la valeur "default", la prise en compte des redirections LDAP par le SDK sous-jacent n'est pas modifiée, la directive LDAPReferralHopLimit ne permet pas de surcharger la "hop limit" du SDK, et aucun "LDAP rebind callback" n'est enregistré.

La directive LDAPReferralHopLimit travaille en conjonction avec cette directive pour limiter le nombre de redirections à suivre pour achever le traitement de la requête LDAP. Lorsque le processus de redirection est activé par la valeur "On", les données d'authentification du client sont transmises via un "rebind callback" à tout serveur LDAP qui en fait la demande.

Directive LDAPRetries

Description: | Définit le nombre maximum de tentatives de connexions au serveur LDAP.
Syntaxe: | LDAPRetries nombre d'essais
Défaut: | LDAPRetries 3
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Suite à des échecs de connexion au serveur LDAP, le serveur tentera de se connecter autant de fois qu'indiqué par la directive LDAPRetries. Si cette directive est définie à 0, le serveur ne tentera pas d'autre connexion après un échec.

Il est possible d'effectuer une autre tentative de connexion en cas d'erreurs LDAP du type délai dépassé ou connexion refusée.

Directive LDAPRetryDelay

Description: | Définit le temps d'attente avant un autre essai de connexion au serveur LDAP.
Syntaxe: | LDAPRetryDelay secondes
Défaut: | LDAPRetryDelay 0
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Si la directive LDAPRetryDelay est définie à une valeur différente de 0, le serveur attendra pendant la durée spécifiée pour envoyer à nouveau sa requête LDAP. Une valeur de 0 implique une absence de délai pour les essais successifs.

Il est possible d'effectuer une autre tentative de connexion en cas d'erreurs LDAP du type délai dépassé ou connexion refusée.

Directive LDAPSharedCacheFile

Description: | Définit le fichier du cache en mémoire partagée
Syntaxe: | LDAPSharedCacheFile chemin/fichier
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier le chemin du fichier du cache en mémoire partagée. Si elle n'est pas définie, la mémoire partagée anonyme sera utilisée si la plate-forme la supporte.

Directive LDAPSharedCacheSize

Description: | Taille en octets du cache en mémoire partagée
Syntaxe: | LDAPSharedCacheSize octets
Défaut: | LDAPSharedCacheSize 500000
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier le nombre d'octets à allouer pour le cache en mémoire partagée. La valeur par défaut est 500kb. Si elle est définie à 0, le cache en mémoire partagée ne sera pas utilisé et chaque processus HTTPD va créer son propre cache.

Directive LDAPTimeout

Description: | Spécifie le délai d'attente pour les opérations de recherche et d'identification LDAP en secondes
Syntaxe: | LDAPTimeout secondes
Défaut: | LDAPTimeout 60
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap
Compatibilité: | Disponible à partir de la version 2.3.5 du serveur HTTP Apache

Cette directive permet de spécifier le délai d'attente pour les opérations de recherche et d'identification, ainsi que l'option LDAP_OPT_TIMEOUT dans la bibliothèque LDAP client sous-jacente, lorsqu'elle est disponible.

Lorsque le délai est atteint, httpd va refaire un essai dans le cas où une connexion existante a été silencieusement fermée par un pare-feu. Les performances seront cependant bien meilleures si le pare-feu est configuré pour envoyer des paquets TCP RST au lieu de rejeter silencieusement les paquets.

Les délais pour les opérations de comparaison LDAP nécessitent un SDK avec LDAP_OPT_TIMEOUT, comme OpenLDAP >= 2.4.4.

Directive LDAPTrustedClientCert

Description: | Définit le nom de fichier contenant un certificat client ou un alias renvoyant vers un certificat client spécifique à une connexion. Tous les SDK LDAP ne supportent pas les certificats clients par connexion.
Syntaxe: | LDAPTrustedClientCert type chemin/nom-fichier/alias [mot de passe]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier le chemin et le nom de fichier ou l'alias d'un certificat client par connexion utilisé lors de l'établissement d'une connexion SSL ou TLS avec un serveur LDAP. Les sections directory ou location peuvent posséder leurs propres configurations de certificats clients. Certains SDK LDAP (en particulier Novell) ne supportent pas les certificats clients par connexion, et renvoient une erreur lors de la connexion au serveur LDAP si vous tenter d'utiliser cette directive (Utilisez à la place la directive LDAPTrustedGlobalCert pour les certificats clients sous Novell - Voir plus haut le guide des certificats SSL/TLS pour plus de détails). Le paramètre type spécifie le type du certificat en cours de définition, en fonction du SDK LDAP utilisé. Les types supportés sont :

  • CA_DER - certificat de CA codé en binaire DER
  • CA_BASE64 - certificat de CA codé en PEM
  • CERT_DER - certificat client codé en binaire DER
  • CERT_BASE64 - certificat client codé en PEM
  • CERT_NICKNAME - certificat client "nickname" (SDK Netscape)
  • KEY_DER - clé privée codée en binaire DER
  • KEY_BASE64 - clé privée codée en PEM

Directive LDAPTrustedGlobalCert

Description: | Définit le nom de fichier ou la base de données contenant les Autorités de Certification de confiance globales ou les certificats clients globaux
Syntaxe: | LDAPTrustedGlobalCert type chemin/nom-fichier [mot de passe]
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier le chemin et le nom du fichier contenant les certificats des CA de confiance et/ou les certificats clients du système global que mod_ldap utilisera pour établir une connexion SSL ou TLS avec un serveur LDAP. Notez que toute information relative aux certificats spécifiée en utilisant cette directive s'applique globalement à l'ensemble de l'installation du serveur. Certains SDK LDAP (en particulier Novell) nécessitent la définition globale de tous les certificats clients en utilisant cette directive. La plupart des autres SDK nécessitent la définition des certificats clients dans une section Directory ou Location en utilisant la directive LDAPTrustedClientCert. Si vous ne définissez pas ces directives correctement, une erreur sera générée lors des tentatives de contact avec un serveur LDAP, ou la connexion échouera silencieusement (Voir plus haut le guide des certificats SSL/TLS pour plus de détails). Le paramètre type spécifie le type de certificat en cours de définition, en fonction du SDK LDAP utilisé. Les types supportés sont :

  • CA_DER - certificat de CA codé en binaire DER
  • CA_BASE64 - certificat de CA codé en PEM
  • CA_CERT7_DB - fichier de base de données des certificats de CA de Netscape cert7.db
  • CA_SECMOD - fichier de base de données secmod de Netscape
  • CERT_DER - certificat client codé en binaire DER
  • CERT_BASE64 - certificat client codé en PEM
  • CERT_KEY3_DB - fichier de base de données des certificats clients de Netscape key3.db
  • CERT_NICKNAME - certificat client "nickname" (SDK Netscape)
  • CERT_PFX - certificat client codé en PKCS#12 (SDK Novell)
  • KEY_DER - clé privée codée en binaire DER
  • KEY_BASE64 - clé privée codée en PEM
  • KEY_PFX - clé privée codée en PKCS#12 (SDK Novell)

Directive LDAPTrustedMode

Description: | Spécifie le mode (SSL ou TLS) à utiliser lors de la connexion à un serveur LDAP.
Syntaxe: | LDAPTrustedMode type
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ldap

Les modes suivants sont supportés :

  • NONE - aucun chiffrement
  • SSL - chiffrement ldaps:// sur le port par défaut 636
  • TLS - chiffrement STARTTLS sur le port par défaut 389

Les modes ci-dessus ne sont pas supportés par tous les SDK LDAP. Un message d'erreur sera généré à l'exécution si un mode n'est pas supporté, et la connexion au serveur LDAP échouera.

Si une URL de type ldaps:// est spécifiée, le mode est forcé à SSL et la définition de LDAPTrustedMode est ignorée.

Directive LDAPVerifyServerCert

Description: | Force la vérification du certificat du serveur
Syntaxe: | LDAPVerifyServerCert On|Off
Défaut: | LDAPVerifyServerCert On
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ldap

Cette directive permet de spécifier s'il faut forcer la vérification d'un certificat de serveur lors de l'établissement d'une connexion SSL avec un serveur LDAP.


mod_log_config - Serveur Apache HTTP Version 2.4

Module Apache mod_log_config

Description: | Journalisation des requêtes envoyées au serveur
Statut: | Base
Identificateur de Module: | log_config_module
Fichier Source: | mod_log_config.c

Sommaire

Ce module apporte une grande souplesse dans la journalisation des requêtes des clients. Les journaux sont écrits sous un format personnalisable, et peuvent être enregistrés directement dans un fichier, ou redirigés vers un programme externe. La journalisation conditionnelle est supportée, si bien que des requêtes individuelles peuvent être incluses ou exclues des journaux en fonction de leur caractéristiques.

Ce module fournit trois directives : TransferLog crée un fichier journal, LogFormat définit un format personnalisé, et CustomLog définit un fichier journal et un format en une seule étape. Pour journaliser les requêtes dans plusieurs fichiers, vous pouvez utiliser plusieurs fois les directives TransferLog et CustomLog dans chaque serveur.

Traitement des bugs

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

Voir aussi

  • Les fichiers journaux d'Apache

Formats de journaux personnalisés

L'argument format des directives LogFormat et CustomLog est une chaîne de caractères. Cette chaîne définit le format de la journalisation des requêtes dans le fichier journal. Elle peut contenir des caractères littéraux qui seront reproduits dans le fichier journal, et les caractères de contrôle de style C "\n" et "\t" représentant respectivement une nouvelle ligne et une tabulation. Les guillemets et les anti-slashes littéraux doivent être échappés à l'aide d'anti-slashes.

Les caractéristiques de la requête en elle-même sont journalisées en insérant des directives "%" dans la chaîne de format, celles-ci étant remplacées dans le fichier journal par certaines valeurs comme suit :

Chaîne de format | Description
%% Le signe "pourcentage"
%a | L'adresse IP distante (voir le module mod_remoteip).
%{c}a | Adresse IP distante de la connexion(voir le module mod_remoteip)
%A | L'adresse IP locale
%B | La taille de la réponse en octets, en excluant les en-têtes HTTP.
%b | La taille de la réponse en octets, en excluant les en-têtes HTTP. Au format CLF , c'est à dire un '-' à la place d'un 0 lorsqu'aucun octet n'est renvoyé.
%{NOMVAR}C | Le contenu du cookie NOMVAR dans la requête envoyée au serveur. Seuls les cookies version 0 sont pleinement supportés.
%D | Le temps mis à servir la requête, en microsecondes.
%{NOMVAR}e | Le contenu de la variable d'environnement NOMVAR
%f | Nom de fichier
%h | Serveur distant. Contiendra l'adresse IP si la directive HostnameLookups est définie à Off, ce qui est sa valeur par défaut. Si cette adresse IP n'est enregistrée que pour certains serveurs, vous avez probablement défini des directives de contrôle d'accès qui mentionnent ces derniers par leurs noms. Voir la documentation de Require host.
%H | Le protocole de la requête
%{NOMVAR}i | Le contenu des lignes d'en-tête NOMVAR: dans la requête envoyée au serveur. Ces en-têtes sont ajoutés par d'autres modules (par exemple mod_headers). Si vous êtes intéressé par ce qu'était l'en-tête de la requête avant d'être modifié par la plupart des modules, utilisez mod_setenvif pour copier l'en-tête dans une variable d'environnement interne et journaliser sa valeur via le champ %{VARNAME}e décrit plus haut.
%k | Nombre de requêtes persistantes en cours pour cette connexion. Interessant si la directive KeepAlive est utilisée ; par exemple, '1' signifie la première requête après la requête initiale, '2' la seconde, etc... ; autrement, il s'agit toujours de 0 (indiquant la requête initiale).
%l | Le nom de connexion distant (en provenance d'identd, si disponible). Affiche un tiret, sauf si mod_ident est présent et si IdentityCheck est à On.
%L | L'identifiant du message de journalisation de la requête dans le journal des erreurs (ou '-' si aucun message n'a été enregistré dans le journal des erreurs pour cette requête)
%m | La méthode de la requête
%{NOMVAR}n | Le contenu de la note NOMVAR en provenance d'un autre module.
%{NOMVAR}o | Le contenu de la ligne d'en-tête NOMVAR: de la réponse.
%p | Le port canonique du serveur servant la requête
%{format}p | Le port canonique du serveur servant la requête ou le véritable port du serveur ou le véritable port du client. les formats valides sont canonical, local, ou remote.
%P | Le numéro de processus du processus enfant qui a servi la requête.
%{format}P | Le numéro de processus ou le numéro de thread du processus enfant qui a servi la requête. Les formats valides sont pid, tid, et hextid. hextid nécessite APR version 1.2.0 ou supérieure.
%q | La chaîne d'arguments (préfixée par un ? si une chaîne d'arguments existe, sinon une chaîne vide)
%r | La première ligne de la requête
%R | Le gestionnaire qui génère la réponse (s'il y en a un).
%s | Statut. Pour les requêtes redirigées en interne, il s'agit du statut de la requête *originale* --- %>s pour la dernière.
%t | Date à laquelle la requête a été reçue (au format anglais standard)
%{format}t La date, sous la forme spécifiée par format, qui devrait être au format étendu strftime(3) (éventuellement localisé). Si le format commence par begin: (valeur par défaut), la date est extraite au début du traitement de la requête ; s'il commence par end:, la date correspond au moment où l'entrée du journal est inscrite, par conséquent vers la fin du traitement de la requête. Hormis les formats supportés par strftime(3), les formats suivants sont aussi disponibles :
sec | nombre de secondes depuis Epoch
msec | nombre de millisecondes depuis Epoch
usec | nombre de microsecondes depuis Epoch
msec_frac | fraction de milliseconde
usec_frac | fraction de microseconde
Ces symboles ne peuvent pas être combinés entre eux ou avec un formatage strftime(3) dans la même chaîne de format. Par contre, vous pouvez utiliser plusieurs symboles %{format}t.
%T | Le temps mis pour servir la requête, en secondes.
%{UNIT}T | Le temps mis pour traiter la requête dans une unité définie par UNIT. Les valeurs d'unité valides sont ms pour millisecondes, us pour microsecondes et s pour secondes. Si UNIT est omis, la valeur de l'unité par défaut est la seconde ; spécifier la valeur d'unité us revient à utiliser le format %D. La possibilité de spécifier une valeur d'unité avec le format %T est disponible depuis la version 2.4.13 du serveur HTTP Apache.
%u | L'utilisateur distant (en provenance d'auth ; peut être faux si le statut de retour (%s) est 401).
%U | Le chemin de la requête, à l'exclusion de toute chaîne d'arguments.
%v | Le nom canonique du serveur qui a servi la requête, défini par la directive ServerName.
%V | La nom du serveur en tenant compte de la définition de la directive UseCanonicalName.
%X Statut de la connexion lorsque la réponse a été renvoyée :
X = | connexion abandonnée avant l'envoi de la réponse.
+ = | la connexion peut rester ouverte après l'envoi de la réponse.
- = | la connexion sera fermée après l'envoi de la réponse.
%I | Le nombre d'octets reçus, en comptant la requête et les en-têtes, ne peut être nul. Nécessite l'activation de mod_logio.
%O | Nombre d'octets envoyés, y compris les en-têtes. Peut être nul dans les rares cas où une requête est avortée avant que la réponse ne soit envoyée. Nécessite l'activation de mod_logio.
%S | Nombre d'octets transmis (en émission et réception), y compris corps et en-têtes de requête. Ce nombre ne peut pas être nul, et il correspond à la combinaison des formats %I et %O. mod_logio doit être chargé pour pouvoir utiliser ce format.
%{VARNAME}^ti | Le contenu de VARNAME: dans les paramètres de la requête envoyée au serveur.
%{VARNAME}^to | Le contenu de VARNAME: dans les paramètres de la réponse envoyée par le serveur.

Modificateurs

Il est possible de restreindre l'enregistrement de certains éléments en fonction du code de statut de la réponse, en insérant une liste de codes de statut séparés par des virgules immédiatement après le caractère "%". Par exemple, "%400,501{User-agent}i" n'enregistrera l'en-tête User-agent que dans le cas d'une erreur 400 ou 501. Avec les autres codes de statut, c'est la chaîne littérale "-" qui sera enregistrée. La liste de codes peut être précédée d'un "!" pour inverser la condition : "%!200,304,302{Referer}i" enregistre l'en-tête Referer pour toutes les requêtes qui ne renvoient pas un des trois codes spécifiés.

Les modificateurs "<" et ">" peuvent être utilisés pour les requêtes qui ont été redirigées en interne afin de choisir si c'est respectivement la requête originale ou finale qui doit être consultée. Par défaut, les directives %s, %U, %T, %D, et %r consultent la requête originale, alors que toutes les autres consultent la requête finale. Ainsi, par exemple, on peut utiliser %>s pour enregistrer le statut final de la requête, et %<u pour enregistrer l'utilisateur authentifié à l'origine pour une requête redirigée en interne vers une ressource sans authentification.

Quelques Notes

Pour des raisons de sécurité, à partir de la version 2.0.46, les caractères non imprimables et autres caractères spéciaux dans les directives %r, %i et %o doivent être échappés à l'aide des séquences \xhh, où hh est le code hexadécimal du caractère spécial. Comme exceptions à cette règle, les caractères " et \ doivent être échappés par un anti-slash, et tous les "blancs" doivent être écrits selon leur notation de style C (\n, \t, etc...). Avant la version 2.0.46, aucun échappement n'était effectué sur ces chaînes, et il fallait être très prudent lors de l'exploitation des journaux bruts.

A la différence de la version 1.3, depuis httpd 2.0, les chaînes de format %b et %B ne représentent pas le nombre d'octets envoyés au client, mais simplement la taille en octets de la réponse HTTP (les deux étant différents, par exemple, si la connexion est abandonnée, ou si SSL est utilisé). Le format %O fourni par mod_logio, enregistrera le nombre réel d'octets envoyés sur le réseau.

Note : mod_cache est implémenté en tant que gestionnaire basique et non en tant que gestionnaire standard. C'est pourquoi la chaîne de format %R ne renverra pas d'information à propos du gestionnaire lorsqu'une mise en cache de contenu entre en jeu.

Exemples

Quelques chaînes de format couramment utilisées :

Format de journal courant (CLF)
"%h %l %u %t \"%r\" %>s %b"
Format de journal courant avec un serveur virtuel
"%v %h %l %u %t \"%r\" %>s %b"
Format de journal NCSA étandu/combiné
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
Format de journal de la page qui contient le lien vers la page concernée (Referer)
"%{Referer}i -> %U"
Format de journal de l'agent (Navigateur)
"%{User-agent}i"

Vous pouvez utiliser plusieurs fois la directive %{format}t pour construire un format de temps utilisant les symboles de format étendus tels que msec_frac :

Format de temps prenant en compte les milisecondes
"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"

Considérations concernant la sécurité

Voir le document conseils à matière de sécurité pour plus de détails sur les raisons pour lesquelles votre sécurité pourrait être compromise, si le répertoire où sont stockés les fichiers journaux sont inscriptibles par tout autre utilisateur que celui qui démarre le serveur.

Directive BufferedLogs

Description: | Enregistre les entrées du journal dans un tampon en mémoire avant de les écrire sur disque
Syntaxe: | BufferedLogs On|Off
Défaut: | BufferedLogs Off
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_log_config

Lorsque la directive BufferedLogs est à "on", mod_log_config stocke de nombreuses entrées du journal en mémoire, et les écrit d'un seul bloc sur disque, plutôt que de les écrire après chaque requête. Sur certains systèmes, ceci peut améliorer l'efficacité des accès disque, et par conséquent les performances. La directive ne peut être définie qu'une seule fois pour l'ensemble du serveur ; elle ne peut pas être définie au niveau d'un serveur virtuel.

Cette directive doit être utilisée avec précautions car un crash peut provoquer la perte de données de journalisation.

Directive CustomLog

Description: | Définit le nom et le format du fichier journal
Syntaxe: | CustomLog fichier|pipe format|alias [env=[!]variable-environnement| expr=expression]
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_log_config

La directive CustomLog permet de contrôler la journalisation des requêtes destinées au serveur. Un format de journal est spécifié, et la journalisation peut s'effectuer de manière conditionnelle en fonction des caractéristiques de la requête en utilisant des variables d'environnement.

Le premier argument, qui spécifie l'emplacement où les journaux seront écrits, accepte deux types de valeurs :

fichier
Un nom de fichier, relatif au répertoire défini par la directive ServerRoot.
pipe
Le caractère pipe "|", suivi du chemin vers un programme qui recevra les informations de la journalisation sur son entrée standard. Voir les notes à propos de la journalisation redirigée pour plus d'informations.

Sécurité :

Si les journaux sont redirigés vers un programme, ce dernier s'exécutera sous l'utilisateur qui a démarré httpd. Ce sera l'utilisateur root si le serveur a été démarré par root ; vérifiez que le programme est sécurisé.

Note

Lors de la spécification d'un chemin de fichier sur les plate-formes non-Unix, il faut prendre soin de ne pas oublier que seuls les slashes directs doivent être utilisés, même si la plate-forme autorise l'emploi d'anti-slashes. D'une manière générale, c'est une bonne idée que de n'utiliser que des slashes directs dans les fichiers de configuration.

Le second argument permet de définir ce qui va être écrit dans le fichier journal. Il peut contenir soit un alias prédéfini par une directive LogFormat, soit une chaîne de format explicite comme décrit dans la section formats de journaux.

Par exemple, les deux blocs de directives suivants produisent le même effet :

# Journal personnalisé avec alias de format
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog "logs/access_log" common

# Journal personnalisé avec chaîne de format explicite
CustomLog "logs/access_log" "%h %l %u %t \"%r\" %>s %b"

Le troisième argument est optionnel et permet de contrôler si une requête doit être ou non journalisée. Dans le cas d'une clause 'env=!nom', la condition peut être la présence ou l'absence d'une variable particulière dans l'environnement du serveur. Dans le cas d'une clause 'expr=expression', la condition consiste en une expression booléenne quelconque. Si la condition n'est pas vérifiée, la requête ne sera pas journalisée. D'éventuelles références à des en-têtes HTTP dans l'expression rationnelle n'entraîneront pas l'ajout des noms d'en-tête correspondants à l'en-tête Vary.

Les variables d'environnement peuvent être définies au niveau de chaque requête en utilisant les modules mod_setenvif et/ou mod_rewrite. Par exemple, si vous voulez enregistrer les requêtes pour toutes les images GIF sur votre serveur dans un fichier journal séparé, et pas dans votre journal principal, vous pouvez utiliser :

SetEnvIf Request_URI \.gif$ gif-image
CustomLog "gif-requests.log" common env=gif-image
CustomLog "nongif-requests.log" common env=!gif-image

Ou, pour reproduire le comportement de l'ancienne directive RefererIgnore, vous pouvez utiliser :

SetEnvIf Referer example\.com localreferer
CustomLog "referer.log" referer env=!localreferer

Directive GlobalLog

Description: | Définit le nom et le format du fichier journal
Syntaxe: | GlobalLogfile|pipe format|nickname [env=[!]environment-variable| expr=expression]
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_log_config
Compatibilité: | Disponible à partir de la version 2.4.19 du serveur HTTP Apache

La directive GlobalLog permet de spécifier un journal partagé entre le serveur principal et tous les serveurs virtuels définis.

Elle est identique à la directive CustomLog à ces différences près :

  • Elle n'est pas valide dans un contexte de serveur virtuel.
  • A la différence d'une directive CustomLog définie globalement, elle est prise en compte par les serveurs virtuels qui définissent leur propre directive CustomLog.

Directive LogFormat

Description: | Décrit un format utilisable dans un fichier journal
Syntaxe: | LogFormat format|alias [alias]
Défaut: | LogFormat "%h %l %u %t \"%r\" %>s %b"
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_log_config

Cette directive permet de spécifier le format du fichier journal des accès.

La directive LogFormat se présente sous deux formes. Sous la première forme, qui ne possède qu'un seul argument, la directive définit le format qui sera utilisé dans les journaux spécifiés par les directives TransferLog ultérieures. L'argument unique peut contenir un format explicite comme décrit dans la section formats de journaux personnalisés ci-dessus. Il peut aussi contenir un alias faisant référence à un format de journal prédéfini par une directive LogFormat comme décrit plus loin.

Sous sa seconde forme, la directive LogFormat associe un format explicite à un alias. Cet alias peut ensuite s'utiliser dans les directives LogFormat ou CustomLog ultérieures, ce qui évite d'avoir à répéter l'ensemble de la chaîne de format. Une directive LogFormat qui définit un alias ne fait rien d'autre -- c'est à dire qu'elle ne fait que définir l'alias, elle n'applique pas le format et n'en fait pas le format par défaut. Par conséquent, elle n'affecte pas les directives TransferLog ultérieures. En outre, la directive LogFormat ne peut pas utiliser un alias pour en définir un autre. Notez que l'alias ne doit pas contenir de caractère pourcent (%).

Exemple

LogFormat "%v %h %l %u %t \"%r\" %>s %b" serveur_virtuel_commun

Directive TransferLog

Description: | Spécifie l'emplacement d'un fichier journal
Syntaxe: | TransferLog fichier|pipe
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_log_config

Cette directive possède exactement les mêmes arguments et produit les mêmes effets que la directive CustomLog, à l'exception qu'elle ne permet pas de spécifier un format de journal explicite ou la journalisation conditionnelle des requêtes. En l'occurrence, le format de journal est déterminé par la dernière définition d'une directive LogFormat qui ne définit pas d'alias. Si aucun format particulier n'a été spécifié, c'est le Common Log Format qui sera utilisé.

Exemple

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log


mod_log_debug - Serveur Apache HTTP Version 2.4

Module Apache mod_log_debug

Description: | Journalisation supplémentaire à des fins de débogage
Statut: | Expérimental
Identificateur de Module: | log_debug_module
Fichier Source: | mod_log_debug.c
Compatibilité: | Disponible depuis la version 2.3.14 d'Apache

Exemples

  1. Enregistre un message après le traitement d'une requête pour /foo/* :
    <Location "/foo/">
  LogMessage "/foo/ has been requested"
</Location>
  2. Enregistre un message si une requête pour /foo/* est traitée dans une sous-requête :
    <Location "/foo/">
  LogMessage "subrequest to /foo/" hook=type_checker "expr=-T %{IS_SUBREQ}"
</Location>
    Le branchement (hook) par défaut log_transaction n'est pas exécuté pour les sous-requêtes ; nous devons donc en utiliser un autre.
  3. Enregistre un message si un client IPv6 est à l'origine d'un dépassement de délai pour une requête :
    LogMessage "IPv6 timeout from %{REMOTE_ADDR}" "expr=-T %{IPV6} && %{REQUEST_STATUS} = 408"
    Notez l'emplacement des guillemets pour l'argument expr=.
  4. Enregistre la valeur de la variable d'environnement de requête "X-Foo" à chaque étape du traitement :
    <Location "/">
  LogMessage "%{reqenv:X-Foo}" hook=all
</Location>
    En association avec les repères de temps en microsecondes du journal des erreurs, hook=all permet aussi de déterminer la durée d'exécution des différentes phases du traitement de la requête.

Directive LogMessage

Description: | Enregistre des messages personnalisés dans le journal des erreurs
Syntaxe: | LogMessage message [hook=hook] [expr=expression]
Défaut: | Non défini
Contexte: | répertoire
Statut: | Expérimental
Module: | mod_log_debug

Cette directive permet d'enregistrer un message personnalisé dans le journal des erreurs. Ce message peut utiliser des variables et des fonctions dans la syntaxe ap_expr. D'éventuelles références à des en-têtes HTTP dans l'expression rationnelle n'entraîneront pas l'ajout des noms d'en-tête correspondants à l'en-tête Vary. Les messages sont enregistrés au loglevel info.

Le branchement (hook) précise la phase du traitement de la requête avant laquelle le message sera enregistré. Les branchements suivants sont supportés :

Nom
translate_name
type_checker
quick_handler
map_to_storage
check_access
check_access_ex
insert_filter
check_authn
check_authz
fixups
handler
log_transaction

Le branchement par défaut est log_transaction. La valeur spéciale all est également supportée ; dans ce cas, le message sera enregistré à chaque phase. Tous les branchements ne sont pas exécutés pour chaque requête.

L'expression optionnelle permet de restreindre l'enregistrement du message en fonction d'une certaine condition. La syntaxe de l'expression est décrite dans la documentation ap_expr. D'éventuelles références à des en-têtes HTTP dans l'expression rationnelle n'entraîneront pas l'ajout des noms d'en-tête correspondants à l'en-tête Vary.


mod_log_forensic - Serveur Apache HTTP Version 2.4

Module Apache mod_log_forensic

Description: | Journalisation légale des requêtes envoyées au serveur
Statut: | Extension
Identificateur de Module: | log_forensic_module
Fichier Source: | mod_log_forensic.c
Compatibilité: | mod_unique_id n'est plus obligatoire depuis la version 2.1

Sommaire

Ce module permet la journalisation légale des requêtes client. La journalisation s'effectuant avant et après le traitement de la requête, le journal légal contient deux lignes pour chaque requête. Le processus de journalisation légale est très strict, à savoir :

  • Le format est figé. Vous ne pouvez pas modifier le format du journal à l'exécution.
  • S'il ne peut pas enregistrer ses données, le processus enfant se termine aussitôt, et peut éventuellement enregistrer un vidage mémoire (selon la définition de la directive CoreDumpDirectory).

Pour interpréter les données du journal légal, vous pouvez vous aider du script check_forensic qui se trouve dans le répertoire support de la distribution.

Note de traduction : le terme "légal" utilisé dans le présent document ne suggère aucunement que ce module apporte une valeur juridique aux journaux. Il est à comprendre dans le contexte similaire à ce que l'on trouve en analyse medico-légale. En d'autres termes, la finalité de ce module est de simplifier les opérations d'investigation autour du traitement des requêtes par le serveur.

Traitement des bugs

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

Voir aussi

  • Les fichiers journaux d'Apache
  • mod_log_config

Format du journal Forensic

Chaque requête fait l'objet d'une double journalisation. La requête est journalisée une première fois avant son traitement (c'est à dire après la réception des en-têtes). La deuxième entrée du journal est écrite après le traitement de la requête, en fait au moment de la journalisation habituelle.

Un identifiant unique est attribué à chaque requête afin de pouvoir l'identifier. Cette identifiant légal peut faire l'objet d'un enregistrement dans le journal standard en utilisant l'élément de chaîne de format %{forensic-id}n. Si vous utilisez mod_unique_id, c'est l'identifiant qu'il génère qui sera utilisé.

La première partie de la journalisation de la requête enregistre l'identifiant légal, la ligne de la requête et tous les en-têtes reçus séparés par des caractères pipe (|). Voici à titre d'exemple à quoi pourrait ressembler une telle entrée (tout étant rassemblé sur une seule ligne) :

+yQtJf8CoAB4AAFNXBIEAAAAA|GET /manual/de/images/down.gif HTTP/1.1|Host:localhost%3a8080|User-Agent:Mozilla/5.0 (X11; U; Linux i686; en-US; rv%3a1.6) Gecko/20040216 Firefox/0.8|Accept:image/png, etc...

Le caractère plus ('+') de début indique qu'il s'agit de la première entrée de journal pour cette requête. La seconde entrée ne contiendra qu'un caractère moins ('-') suivi de l'identifiant :

-yQtJf8CoAB4AAFNXBIEAAAAA

Le script check_forensic prend comme argument le nom du fichier journal. Il recherche ces paires d'identifiants +/- et affiche un message d'erreur si la journalisation d'une requête n'est pas complète.

Considérations à propos de sécurité

Voir le document conseils en matière de sécurité pour des détails sur les raisons pour lesquelles votre sécurité pourrait être compromise si le répertoire dans lequel les fichiers journaux sont stockés sont inscriptibles par tout autre utilisateur que celui qui démarre le serveur.

Les fichiers journaux peuvent contenir des données sensibles comme le contenu des en-têtes Authorization: (qui peuvent contenir des mots de passe) ; ils ne doivent donc être lisibles que par l'utilisateur qui démarre le serveur.

Directive ForensicLog

Description: | Définit le nom de fichier du journal légal
Syntaxe: | ForensicLog nom-fichier|pipe
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_log_forensic

La directive ForensicLog permet de contrôler la journalisation des requêtes à des fins d'analyse légale. Chaque entrée du journal se voit assigner un identifiant unique qui peut être associé à la requête en utilisant la directive CustomLog habituelle. mod_log_forensic crée un élément nommé forensic-id, qui peut être ajouté au journal standard en utilisant l'élément de format %{forensic-id}n.

L'argument, qui permet de spécifier l'emplacement vers lequel le journal légal sera écrit, peut contenir les deux types de valeurs suivants :

nom-fichier
Un nom de fichier relatif au répertoire défini par la directive ServerRoot.
pipe
Le caractère pipe "|", suivi du chemin vers un programme qui recevra les informations de la journalisation sur son entrée standard. Le nom du programme peut être relatif au répertoire défini par la directive ServerRoot.

Sécurité :

Si les journaux sont redirigés vers un programme, ce dernier s'exécutera sous l'utilisateur qui a démarré httpd. Ce sera l'utilisateur root si le serveur a été démarré par root ; vérifiez que le programme est sécurisé ou passe sous le contrôle d'un utilisateur possédant des droits restreints.

Note

Lors de la spécification d'un chemin de fichier sur les plate-formes non-Unix, il faut prendre soin de ne pas oublier que seuls les slashes directs doivent être utilisés, même si la plate-forme autorise l'emploi d'anti-slashes. D'une manière générale, c'est une bonne idée que de n'utiliser que des slashes directs dans les fichiers de configuration.


mod_logio - Serveur Apache HTTP Version 2.4

Module Apache mod_logio

Description: | Journalisation des octets en entrée et en sortie pour chaque requête
Statut: | Extension
Identificateur de Module: | logio_module
Fichier Source: | mod_logio.c

Sommaire

Ce module permet d'enregistrer le nombre d'octets reçus et envoyés pour chaque requête. Ce nombre reflète le nombre réel d'octets transmis sur le réseau, et prend en compte les en-têtes et corps des requêtes et des réponses. Le décompte est effectué avant SSL/TLS en entrée et après SSL/TLS en sortie, si bien que le résultat reflètera toute modification introduite par le chiffrement.

Pour fonctionner, ce module requiert le chargement du module mod_log_config.

Lorsqu'on utilise les connexions persistantes avec SSL, le supplément de trafic induit par la négociation SSL est enregistré dans le décompte des octets transmis dans le cadre de la première requête de la connexion. Lors d'une renégociation SSL au niveau d'un répertoire, le décompte d'octets est associé à la requête qui a déclenché la renégociation.

Traitement des bugs

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

Voir aussi

  • mod_log_config
  • Les fichiers journaux d'Apache

Formats de journaux personnalisés

Ce module introduit trois nouvelles directives de journalisation. Les caractéristiques de la requête en elle-même sont journalisées en insérant des directives "%" dans la chaîne de format, qui seront remplacées comme suit dans le fichier journal :

Chaîne de Format | Description
%I | Octets reçus, en-têtes et corps de requête inclus ; ne peut pas être nul.
%O | Octets envoyés, en-têtes inclus ; ne peut pas être nul.
%S | Nombre d'octets transmis (en émission et réception), y compris corps et en-têtes de requête. Ce nombre ne peut pas être nul, et il correspond à la combinaison des formats %I et %O. Disponible depuis la version 2.4.7 du serveur HTTP Apache.
%^FB | Délai en microsecondes entre l'arrivée de la requête et l'écriture du premier octet des en-têtes de la réponse. Disponible uniquement si la directive LogIOTrackTTFB a été définie à ON. Disponible à partir de la version 2.4.13 du serveur HTTP Apache

En général, cette fonctionnalité s'utilise comme suit :

Format de journal d'entrées/sorties combiné :
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %I %O"

Directive LogIOTrackTTFB

Description: | Permet d'enregistrer le délai avant le premier octet (time to first byte - TTFB)
Syntaxe: | LogIOTrackTTFB ON|OFF
Défaut: | LogIOTrackTTFB OFF
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Extension
Module: | mod_logio
Compatibilité: | Disponible à partir de la version 2.4.13 du serveur HTTP Apache

Cette directive permet de définir si ce module mesure le délai entre la lecture de la requête et l'écriture du premier octet des en-têtes de la réponse. La valeur obtenue peut être enregistrée dans le journal via le format %^FB.


mod_lua - Serveur Apache HTTP Version 2.4

Module Apache mod_lua

Description: | Fournit des points d'entrée Lua dans différentes parties du traitement des requêtes httpd
Statut: | Expérimental
Identificateur de Module: | lua_module
Fichier Source: | mod_lua.c
Compatibilité: | versions 2.3 et supérieures

Sommaire

Ce module permet d'ajouter au serveur des extensions sous forme de scripts écrits dans le langage de programmation Lua. mod_lua fournit de nombreuses extensions (hooks) disponibles avec les modules natifs du serveur HTTP Apache, comme les associations de requêtes à des fichiers, la génération de réponses dynamiques, le contrôle d'accès, l'authentification et l'autorisation.

Vous trouverez davantage d'informations à propos du langage de programmation Lua sur le site web de Lua.

mod_lua est encore au stade expérimental. Son mode d'utilisation et son comportement pourront changer à tout moment jusqu'à ce qu'il passe au stade stable, et ce même entre deux versions stables 2.4.x. N'oublez pas de consulter le fichier CHANGES avant toute mise à jour.

Avertissement

Ce module possède une grande capacité d'action sur le fonctrionnement de httpd, ce qui lui confère une grande puissance, mais peut aussi induire un risque de sécurité. Il est déconseillé d'utiliser ce module sur un serveur partagé avec des utilisateurs auxquels vous ne pouvez pas accorder une confiance absolue, car il peut permettre de modifier le fonctionnement interne de httpd.

Configuration de base

La directive de base pour le chargement du module est

LoadModule lua_module modules/mod_lua.so

mod_lua fournit un gestionnaire nommé lua-script qui peut être utilisé avec une directive AddHandler ou SetHandler :

<Files "*.lua">
    SetHandler lua-script
</Files>

Ceci aura pour effet de faire traiter les requêtes pour les fichiers dont l'extension est .lua par mod_lua en invoquant cette fonction de gestion de fichier.

Pour plus de détails, voir la directive LuaMapHandler.

Ecrire des gestionnaires

Dans l'API du serveur HTTP Apache, un gestionnaire est une sorte de point d'accroche (hook) spécifique responsable de la génération de la réponse. mod_proxy, mod_cgi et mod_status sont des exemples de modules comportant un gestionnaire.

mod_lua cherche toujours à invoquer une fonction Lua pour le gestionnaire, plutôt que de simplement évaluer le corps d'un script dans le style de CGI. Une fonction de gestionnaire se présente comme suit :

example.lua

-- exemple de gestionnaire

require "string"

--[[
     Il s'agit du nom de méthode par défaut pour les gestionnaires Lua ;
     voir les noms de fonctions optionnels dans la directive
     LuaMapHandler pour choisir un point d'entrée différent.
--]]
function handle(r)
    r.content_type = "text/plain"

    if r.method == 'GET' then
        r:puts("Hello Lua World!\n")
        for k, v in pairs( r:parseargs() ) do
            r:puts( string.format("%s: %s\n", k, v) )
        end
    elseif r.method == 'POST' then
        r:puts("Hello Lua World!\n")
        for k, v in pairs( r:parsebody() ) do
            r:puts( string.format("%s: %s\n", k, v) )
        end
    else
    elseif r.method == 'PUT' then
-- message d'erreur personnalisé
        r:puts("Unsupported HTTP method " .. r.method)
    r.status = 405
        return apache2.OK
    else
-- message d'erreur ErrorDocument
        return 501
    end
    return apache2.OK
end

Ce gestionnaire se contente d'afficher les arguments codés d'un uri ou d'un formulaire dans un page au format texte.

Cela signifie que vous pouvez (et êtes encouragé à) avoir plusieurs gestionnaires (ou points d'entrée, ou filtres) dans le même script.

Ecriture de fournisseurs d'autorisation

mod_authz_core fournit une interface d'autorisation de haut niveau bien plus facile à utiliser que dans les hooks correspondants. Le premier argument de la directive Require permet de spécifier le fournisseur d'autorisation à utiliser. Pour chaque directive Require, mod_authz_core appellera le fournisseur d'autorisation spécifié, le reste de la ligne constituant les paramètres. Le fournisseur considéré va alors vérifier les autorisations et fournir le résultat dans une valeur de retour.

En général, le fournisseur authz est appelé avant l'authentification. S'il doit connaître le nom d'utilisateur authentifié (ou si l'utilisateur est appelé à être authentifié), le fournisseur doit renvoyer apache2.AUTHZ_DENIED_NO_USER, ce qui va déclancher le processus d'authentification et un deuxième appel du fournisseur authz.

La fonction du fournisseur authz ci-dessous accepte deux arguments, une adresse IP et un nom d'utilisateur. Elle autorise l'accès dans le cas où la requête provient de l'adresse IP spécifiée, ou si l'utilisateur authentifié correspond au second argument :

authz_provider.lua

require 'apache2'

function authz_check_foo(r, ip, user)
    if r.useragent_ip == ip then
        return apache2.AUTHZ_GRANTED
    elseif r.user == nil then
        return apache2.AUTHZ_DENIED_NO_USER
    elseif r.user == user then
        return apache2.AUTHZ_GRANTED
    else
        return apache2.AUTHZ_DENIED
    end
end

La configuration suivante enregistre cette fonction en tant que fournisseur foo, et la configure por l'URL / :

LuaAuthzProvider foo authz_provider.lua authz_check_foo
<Location "/">
  Require foo 10.1.2.3 john_doe
</Location>

Ecriture de fonctions d'accroche (hooks)

Les fonctions d'accroche déterminent la manière dont les modules (et les scripts Lua) participent au traitement des requêtes. Chaque type d'accroche proposé par le serveur a un rôle spécifique, comme l'association de requêtes au système de fichiers, le contrôle d'accès, ou la définition de types MIME :

Phase d'accroche | Directive mod_lua | Description
Gestionnaire rapide | LuaQuickHandler | Il s'agit de la première accroche appelée lorsqu'une requête a été associée à un serveur ou un serveur virtuel.
Phase de traduction | LuaHookTranslateName | Cette phase traduit l'URI de la requête en nom de fichier sur le système. Ce sont des modules comme mod_alias et mod_rewrite qui interviennent au cours de cette phase.
Choix du lieu de stockage de la ressource | LuaHookMapToStorage | Cette phase définit le lieu de stockage de la ressource : physique, en cache ou externe/mandaté. Elle est assurée par les modules de mandat ou de mise en cache.
Autorisation d'accès | LuaHookAccessChecker | Cette phase vérifie si un client a l'autorisation d'accès à la ressource. Elle s'exécute avant l'authentification de l'utisateur ; il faut donc être prudent.
Vérification de l'identifiant utilisateur | LuaHookCheckUserID | Cette phase vérifie l'identifiant de l'utilisateur ayant fait l'objet d'une négociation.
Vérification de l'autorisation d'accès | LuaHookAuthChecker ou LuaAuthzProvider | Cette phase vérifie l'autorisation d'accès d'un utilisateur en fonction des ses paramètres de connexion, comme l'identifiant, le certificat, etc...
Vérification du type de la ressource | LuaHookTypeChecker | Cette phase assigne un type de contenu et un gestionnaire à la ressource.
Derniers réglages | LuaHookFixups | C'est la dernière phase avant l'activation des gestionnaires de contenu. Toute modification de dernière minute à la requête doit être effectuée ici.
Gestionnaire de contenu | fichiers fx. .lua ou directive LuaMapHandler | C'est durant cette phase que le contenu est traité. Les fichiers sont lus, interprétés, certains sont exécutés, et le résultat obtenu est envoyé au client.
Journalisation | LuaHookLog | Lorsqu'une requête a été traitée, plusieurs phases de journalisation interviennent, et enregistrent leurs résultats dans les fichiers d'erreur ou d'accès. Mod_lua peut s'intercaler au départ de ce processus et ainsi contrôler la journalisation.

Les fonctions d'accroche reçoivent l'objet de la requête comme seul argument (sauf LuaAuthzProvider qui reçoit aussi des arguments en provenance de la directive Require). Elles peuvent renvoyer une valeur, selon la fonction, mais il s'agit en général d'un code d'état HTTP ou des valeurs OK, DONE, ou DECLINED, que vous pouvez écrire dans Lua sous la forme apache2.OK, apache2.DONE, ou apache2.DECLINED.

translate_name.lua

-- exemple d'accroche qui réécrit un URI en chemin du système de fichiers.

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.filename = r.document_root .. "/find_me.txt"
        return apache2.OK
    end
    -- on ne gère pas cette URL et on donne sa chance à un autre module
    return apache2.DECLINED
end
translate_name2.lua

--[[ exemple d'accroche qui réécrit un URI vers un autre URI. Il renvoie
    un apache2.DECLINED pour permettre à un autre interpréteur d'URL de
    travailler sur la substitution, y compris l'accroche translate_name
    de base dont les tables de correspondances se basent sur DocumentRoot.

     Note: utilisez le drapeau early/late de la directive pour
     l'exécuter avant ou après mod_alias.
--]]

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.uri = "/find_me.txt"
        return apache2.DECLINED
    end
    return apache2.DECLINED
end

Structures de données

request_rec

request_rec est considérée en tant que donnée utilisateur. Elle possède une métatable qui vous permet d'accomplir des choses intéressantes. Pour la plus grande partie, elle possède les mêmes champs que la structure request_rec, la plupart d'entre eux étant accessibles en lecture et écriture (le contenu des champs de la table peut être modifié, mais les champs eux-mêmes ne peuvent pas être établis en tant que tables distinctes).

Nom | Type Lua | Modifiable | Description
allowoverrides | string | non | L'option AllowOverride s'applique à la requête courante.
ap_auth_type | string | non | Ce champ contient le type d'authentification effectuée (par exemple basic)
args | string | oui | La chaîne de paramètres de la requête (par exemple foo=bar&name=johnsmith)
assbackwards | boolean | non | contient true s'il s'agit d'une requête de style HTTP/0.9 (par exemple GET /foo (sans champs d'en-tête) )
auth_name | string | non | La chaîne d'identification utilisée pour la vérification de l'autorisation d'accès (si elle est disponible).
banner | string | non | La bannière du serveur, par exemple Apache HTTP Server/2.4.3 openssl/0.9.8c
basic_auth_pw | string | non | Le mot de passe pour l'authentification de base envoyé avec la requête, s'il existe
canonical_filename | string | non | Le nom de fichier canonique de la requête
content_encoding | string | non | Le type de codage du contenu de la requête courante
content_type | string | oui | Le type de contenu de la requête courante, tel qu'il a été déterminé au cours de la phase type_check (par exemple image/gif ou text/html)
context_prefix | string | non
context_document_root | string | non
document_root | string | non | La racine des documents du serveur
err_headers_out | table | non | L'en-tête MIME de l'environnement pour la réponse, écrit même en cas d'erreur et conservé pendant les redirections internes
filename | string | oui | Le nom de fichier correspondant à la requête, par exemple /www/example.com/foo.txt. Il peut être modifié au cours des phases translate-name ou map-to-storage du traitement de la requête pour permettre au gestionnaire par défaut (ou aux gestionnaires de script) de servir une version du fichier autre que celle demandée.
handler | string | oui | Le nom du gestionnaire qui doit traiter la requête, par exemple lua-script si elle doit être traitée par mod_lua. Cette valeur est en général définie via les directives AddHandler ou SetHandler, mais peut aussi l'être via mod_lua pour permettre à un autre gestionnaire de traiter une requête spécifique qui ne serait pas traitée par défaut par ce dernier.
headers_in | table | oui | Les en-têtes MIME de l'environnement de la requête. Il s'agit des en-têtes comme Host, User-Agent, Referer, etc...
headers_out | table | oui | Les en-têtes MIME de l'environnement de la réponse.
hostname | string | non | Le nom d'hôte, tel que défini par l'en-tête Host: ou par un URI complet.
is_https | boolean | non | Indique si la requête à été faite via HTTPS
is_initial_req | boolean | non | Indique si la requête courante est la requête initiale ou une sous-requête.
limit_req_body | number | non | La taille maximale du corps de la requête, ou 0 si aucune limite.
log_id | string | non | L'identifiant de la requête dans les journaux d'accès ou d'erreur.
method | string | non | La méthode de la requête, par exemple GET ou POST.
notes | table | oui | Une liste de notes qui peuvent être transmises d'un module à l'autre.
options | string | non | La valeur de la directive Options pour la requête courante.
path_info | string | non | La valeur de PATH_INFO extraite de la requête.
port | number | non | Le port du serveur utilisé par la requête.
protocol | string | non | Le protocole utilisé, par exemple HTTP/1.1
proxyreq | string | oui | Indique s'il s'agit d'une requête mandatée ou non. Cette valeur est en général définie au cours de la phase post_read_request/translate_name du traitement de la requête.
range | string | non | Le contenu de l'en-tête Range:.
remaining | number | non | Le nombre d'octets du corps de la requête restant à lire.
server_built | string | non | La date de compilation du serveur.
server_name | string | non | Le nom du serveur pour cette requête.
some_auth_required | boolean | non | Indique si une autorisation est/était requise pour cette requête.
subprocess_env | table | oui | Le jeu de variables d'environnement pour cette requête.
started | number | non | Le moment où le serveur a été (re)démarré, en secondes depuis epoch (1er janvier 1970)
status | number | oui | Le code de retour (courant) pour cette requête, par exemple 200 ou 404.
the_request | string | non | La chaîne de la requête telle qu'elle a été envoyée par le client, par exemple GET /foo/bar HTTP/1.1.
unparsed_uri | string | non | La partie URI non interprétée de la requête
uri | string | oui | L'URI après interprétation par httpd
user | string | oui | Si une authentification a été effectuée, nom de l'utilisateur authentifié.
useragent_ip | string | non | L'adresse IP de l'agent qui a envoyé la requête

Méthodes de l'objet request_rec

L'objet request_rec possède (au minimum) les méthodes suivantes :

r:flush()   -- vide le tampon de sortie
            -- Renvoie true si le vidage a été effectué avec succès,
        -- false dans le cas contraire.

while nous_avons_des_données_à_envoyer do
    r:puts("Bla bla bla\n") -- envoi des données à envoyer vers le tampon
    r:flush() -- vidage du tampon (envoi au client)
    r.usleep(500000) -- mise en attente pendant 0.5 secondes et bouclage
end
r:addoutputfilter(name|function) -- ajoute un filtre en sortie

r:addoutputfilter("fooFilter") -- insère le filtre fooFilter dans le flux de sortie
r:sendfile(filename) -- envoie un fichier entier au client en utilisant sendfile s'il est
                     -- supporté par la plateforme :

if use_sendfile_thing then
    r:sendfile("/var/www/large_file.img")
end
r:parseargs() -- renvoie deux tables : une table standard de couples
              -- clé/valeur pour les données GET simples,
              -- et une autre pour les données
              -- multivaluées (par exemple foo=1&foo=2&foo=3) :

local GET, GETMULTI = r:parseargs()
r:puts("Votre nom est : " .. GET['name'] or "Unknown")
r:parsebody()([sizeLimit]) -- interprète le corps de la
                           -- requête en tant que POST et renvoie
                           -- deux tables lua, comme r:parseargs(). Un
                           -- nombre optionnel peut être fourni
                           -- pour spécifier le nombre maximal
                           -- d'octets à interpréter. La
                           -- valeur par défaut est 8192.

local POST, POSTMULTI = r:parsebody(1024*1024)
r:puts("Votre nom est : " .. POST['name'] or "Unknown")
r:puts("bonjour", " le monde", "!") -- affichage dans le corps de la réponse
r:write("une simple chaîne") -- affichage dans le corps de la réponse
r:escape_html("<html>test</html>") -- Echappe le code HTML et renvoie le résultat
r:base64_encode(string) -- Encode une chaîne à l'aide du standard de codage Base64.

local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=
r:base64_decode(string) -- Décode une chaîne codée en Base64.

local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'
r:md5(string) -- Calcule et renvoie le condensé MD5 d'une chaîne en mode binaire (binary safe).

local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339
r:sha1(string) -- Calcule et renvoie le condensé SHA1 d'une chaîne en mode binaire (binary safe).

local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19
r:escape(string) -- Echappe une chaîne de type URL.

local url = "http://foo.bar/1 2 3 & 4 + 5"
local escaped = r:escape(url) -- renvoie 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'
r:unescape(string) -- Déséchappe une chaîne de type URL.

local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
local unescaped = r:unescape(url) -- renvoie 'http://foo.bar/1 2 3 & 4 + 5'
r:construct_url(string) -- Construit une URL à partir d'un URI

local url = r:construct_url(r.uri)
r.mpm_query(number) -- Interroge le serveur à propos de son module MPM via la requête ap_mpm_query.

local mpm = r.mpm_query(14)
if mpm == 1 then
    r:puts("Ce serveur utilise le MPM Event")
end
r:expr(string) -- Evalue une chaîne de type expr.

if r:expr("%{HTTP_HOST} =~ /^www/") then
    r:puts("Ce nom d'hôte commence par www")
end
r:scoreboard_process(a) -- Interroge le serveur à propos du
                        -- processus à la position a.

local process = r:scoreboard_process(1)
r:puts("Le serveur 1 a comme PID " .. process.pid)
r:scoreboard_worker(a, b) -- Interroge le serveur à propos du
                          -- thread b, dans le processus a.

local thread = r:scoreboard_worker(1, 1)
r:puts("L'ID du thread 1 du serveur 1 est " .. thread.tid .. " et son
état est " .. thread.status)
r:clock() -- Renvoie l'heure courante avec une précision d'une microseconde.
r:requestbody(filename) -- Lit et renvoie le corps d'une requête.
                        -- Si 'filename' est spécifié, le
                        -- corps de requête n'est pas
                        -- renvoyé, mais sauvegardé dans
                        -- le fichier correspondant.

local input = r:requestbody()
r:puts("Vous m'avez envoyé le corps de requête suivant :\n")
r:puts(input)
r:add_input_filter(filter_name) -- Ajoute le filtre en entrée 'filter_name'.
r:module_info(module_name) -- Interroge le serveur à propos d'un module.

local mod = r.module_info("mod_lua.c")
if mod then
    for k, v in pairs(mod.commands) do
       r:puts( ("%s: %s\n"):format(k,v)) -- affiche toutes les directives
                                         -- implémentées par ce module.
    end
end
r:loaded_modules() -- Renvoie une liste des modules chargés par httpd.

for k, module in pairs(r:loaded_modules()) do
    r:puts("J'ai chargé le module " .. module .. "\n")
end
r:runtime_dir_relative(filename) -- Génère le nom d'un fichier run-time
                                 -- (par exemple la mémoire partagée
                                 -- "file") relativement au répertoire de run-time.
r:server_info() -- Renvoie une table contenant des informations à
                -- propos du serveur, comme le nom de
                -- l'exécutable httpd, le module mpm utilisé, etc...
r:set_document_root(file_path) -- Définit la racine des documents
                               -- pour la requête à file_path.
r:add_version_component(component_string) -- Ajoute un élément à
                                          -- la bannière du serveur.
r:set_context_info(prefix, docroot) -- Définit le préfixe et la
                                    -- racine des documents du contexte pour une requête.
r:os_escape_path(file_path) -- Convertit un chemin du système de
                            -- fichiers en URL indépendamment du système d'exploitation.
r:escape_logitem(string) -- Echappe une chaîne pour journalisation.
r.strcmp_match(string, pattern) -- Vérifie si 'string' correspond à
                                -- 'pattern' via la fonction strcmp_match (GLOBs). Par exemple, est-ce que
                                -- 'www.example.com' correspond à '*.example.com' ?

local match = r.strcmp_match("foobar.com", "foo*.com")
if match then
    r:puts("foobar.com matches foo*.com")
end
r:set_keepalive() -- Définit l'état de persistance d'une requête.
                  -- Renvoie true dans la mesure du possible, false dans le cas contraire.
r:make_etag() -- Génère et renvoie le etag pour la requête courante.
r:send_interim_response(clear) -- Renvoie une réponse d'intérim (1xx) au
                               -- client. Si 'clear' est vrai, les en-têtes disponibles
                               -- seront envoyés et effacés.
r:custom_response(status_code, string) -- Génère et définit une réponse
                                       -- personnalisée pour un code d'état particulier.
                                       -- Le fonctionnement est très proche de celui de la directive ErrorDocument.

r:custom_response(404, "Baleted!")
r.exists_config_define(string) -- Vérifie si une définition de configuration existe.

if r.exists_config_define("FOO") then
    r:puts("httpd a probablement été lancé avec l'option -DFOO, ou FOO a
    été défini dans la configuration")
end
r:state_query(string) -- Interroge le serveur à propos de son état.
r:stat(filename [,wanted]) -- Exécute stat() sur un fichier, et renvoie une table contenant
                           -- des informations à propos de ce fichier.

local info = r:stat("/var/www/foo.txt")
if info then
    r:puts("Ce fichier existe et a été modifié pour la dernière fois à : " .. info.modified)
end
r:regex(string, pattern [,flags]) -- Exécute une recherche à base d'expression rationnelle
                                  -- sur une chaîne, et renvoie les éventuelles correspondances trouvées.

local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
if matches then
    r:puts("L'expression rationnelle correspond et le dernier mot
    capturé ($2) est : " .. matches[2])
end

-- Exemple avec insensibilité à la casse :
local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)

-- les drapeaux peuvent être une combibaison bit à bit de :
-- 0x01: insensibilité à la casse
-- 0x02: recherche multiligne
r.usleep(microsecondes) -- Interrompt l'exécution du script pendant le nombre de microsecondes spécifié.
r:dbacquire(dbType[, dbParams]) -- Acquiert une connexion à une base de données et renvoie une classe database.
                                -- Voir 'Connectivité aux bases de données'
                -- pour plus de détails.
r:ivm_set("key", value) -- Défini une variable Inter-VM avec une valeur spécifique.
                        -- Ces valeurs sont conservées même si la VM est
            -- arrêtée ou non utilisée, et ne doivent donc être
            -- utilisées que si MaxConnectionsPerChild > 0.
            -- Les valeurs peuvent être de type number, string
            -- ou boolean et sont stockées séparément pour
            -- chaque processus (elles ne seront donc pas d'une
            -- grande utilité si l'on utilise le mpm prefork).

r:ivm_get("key")        -- Lit le contenu d'une variable définie via ivm_set. Renvoie
            -- le contenu de la variable si elle existe, ou nil
            -- dans le cas contraire.

-- Voici un exemple de lecture/écriture qui sauvegarde une variable
-- globale en dehors de la VM :
function handle(r)
    -- La première VM qui effectue l'appel suivant n'obtiendra aucune
    -- valeur, et devra la créer
    local foo = r:ivm_get("cached_data")
    if not foo then
        foo = do_some_calcs() -- simulation de valeurs de retour
        r:ivm_set("cached_data", foo) -- définition globale de la variable
    end
    r:puts("La donnée en cache est : ", foo)
end
r:htpassword(string [,algorithm [,cost]]) -- Génère un hash de mot de passe à partir d'une chaîne.
                                          -- algorithm: 0 = APMD5 (défaut), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
                                          -- cost: ne s'utilise qu'avec l'algorythme BCRYPT (défaut = 5).
r:mkdir(dir [,mode]) -- Crée un répertoire et définit son mode via le paramètre optionnel mode.
r:mkrdir(dir [,mode]) -- Crée des répertoires de manière récursive et définit
                      -- leur mode via le paramètre optionnel mode.
r:rmdir(dir) -- Supprime un répertoire.
r:touch(file [,mtime]) -- Définit la date de modification d'un fichier à la date courante ou à
                       -- la valeur optionnelle mtime en msec.
r:get_direntries(dir) -- Renvoie une table contenant toutes les entrées de répertoires.

-- Renvoie un chemin sous forme éclatée en chemin, fichier, extension
function handle(r)
  local dir = r.context_document_root
  for _, f in ipairs(r:get_direntries(dir)) do
    local info = r:stat(dir .. "/" .. f)
    if info then
      local mtime = os.date(fmt, info.mtime / 1000000)
      local ftype = (info.filetype == 2) and "[dir] " or "[file]"
      r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
    end
  end
end
r.date_parse_rfc(string) -- Interprète une chaîne date/heure et renvoie l'équivalent en secondes depuis epoche.
r:getcookie(key) -- Obtient un cookie HTTP
r:setcookie(key, value, secure, expires) -- Définit un cookie HTTP, par exemple :
r:setcookie("foo", "bar and stuff", false, os.time() + 86400)
r:wsupgrade() -- Met à jour une connexion vers les WebSockets si possible (et si demandé) :
if r:wsupgrade() then -- si la mise à jour est possible :
    r:wswrite("Bienvenue dans les websockets!") -- écrit quelque chose à l'intention du client
    r:wsclose()  -- Au revoir !
end
r:wsread() -- Lit un cadre de websocket depuis une connexion vers websocket mise à jour (voir ci-dessus) :

local line, isFinal = r:wsread() -- isFinal indique s'il s'agit du cadre final.
                                 -- dans le cas contraire, on peut lire les cadres suivants
r:wswrite("Vous avez écrit : " .. line)
r:wswrite(line) -- écrit un cadre vers un client WebSocket :
r:wswrite("Bonjour le Monde !")
r:wsclose() -- ferme une requête WebSocket et l'achève pour httpd :

if r:wsupgrade() then
    r:wswrite("Ecrire quelque chose : ")
    local line = r:wsread() or "nothing"
    r:wswrite("Vous avez écrit : " .. line);
    r:wswrite("Au revoir !")
    r:wsclose()
end

Fonctions de journalisation

    -- exemples de messages de journalisation
    r:trace1("Ceci est un message de journalisation de niveau
    trace") -- les niveaux valides vont de trace1 à trace8
        r:debug("Ceci est un message de journalisation de niveau debug")
        r:info("Ceci est un message de journalisation de niveau info")
        r:notice("Ceci est un message de journalisation de niveau notice")
        r:warn("Ceci est un message de journalisation de niveau warn")
        r:err("Ceci est un message de journalisation de niveau err")
        r:alert("Ceci est un message de journalisation de niveau alert")
        r:crit("Ceci est un message de journalisation de niveau crit")
        r:emerg("Ceci est un message de journalisation de niveau emerg")

Paquet apache2

Le paquet nommé apache2 est fourni avec (au minimum) le contenu suivant :

apache2.OK
Constante interne OK. Les gestionnaires renverront cette valeur s'ils ont traité la requête.
apache2.DECLINED
Constante interne DECLINED. Les gestionnaires renverront cette valeur s'ils n'ont pas l'intention de traiter la requête.
apache2.DONE
Constante interne DONE.
apache2.version
Chaîne contenant la version du serveur HTTP Apache
apache2.HTTP_MOVED_TEMPORARILY
Code d'état HTTP
apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE
Constantes internes utilisées par mod_proxy
apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER
constantes internes utilisées par mod_authz_core

Les autres codes d'état HTTP ne sont pas encore implémentés.

Modification de contenu avec les filtres lua

Les fonctions de filtrage implémentées via les directives LuaInputFilter ou LuaOutputFilter sont conçues comme des fonctions de 3ème phase non blocantes utilisant des sous-routines pour suspendre et reprendre l'exécution d'une fonction lorsque des paquets de données sont envoyés à la chaîne de filtrage. La structure de base d'une telle fonction est :

function filter(r)
    -- Nous indiquons tout d'abord que nous sommes prêts à recevoir des
    -- blocs de données.
    -- Avant ceci, nous pouvons définir notre environnement, tester
    -- certaines conditions, et, si nous le jugeons nécessaire, refuser le
    -- filtrage d'une requête :
    if something_bad then
        return -- Le filtrage est sauté
    end
    -- Sans se préoccuper des données que nous devons éventuellement ajouter, un arrêt est réalisé ici.
    -- Noter que les filtres de sortie sont les seuls capables d'ajouter des éléments au début des données.
    -- Les filtres en entrée peuvent ajouter des éléments à la fin des données au stade final.

    coroutine.yield([optional header to be prepended to the content])

    -- Après cet arrêt, nous allons recevoir d'autres blocs de données, un par un ;
    -- nous pouvons les traiter comme il nous plaît et procéder à la réponse.
    -- Ces blocs sont conservés dans la variable globale 'bucket', nous réalisons donc
    -- une boucle pour vérifier que 'bucket' n'est pas vide :
    while bucket ~= nil do
        local output = mangle(bucket) -- Do some stuff to the content
        coroutine.yield(output) -- Return our new content to the filter chain
    end

    -- Une fois les blocs de données épuisés, 'bucket' est positionné à une valeur vide ('nil'),
    -- ce qui va nous faire sortir de cette boucle et nous amener à l'étape suivante.
    -- On peut ajouter ce qu'on veut à la fin des données à cette étape, qui constitue le dernier
    -- arrêt. Les filtres d'entrée comme de sortie peuvent servir à ajouter des éléments à la fin
    --  des données à cette étape.
    coroutine.yield([optional footer to be appended to the content])
end

Connectivité aux bases de données

Mod_lua implémente une fonctionnalité basique de connexion aux bases de données permettant d'envoyer des requêtes ou d'exécuter des commandes auprès des moteurs de base de données les plus courants (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle), ainsi que mod_dbd.

L'exemple suivant montre comment se connecter à une base de données et extraire des informations d'une table :

function handle(r)
    -- connexion à la base de données
    local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb")
    if not err then
        -- Sélection de certaines informations
        local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
        if not err then
            local rows = results(0) -- extrait tous les enregistrements en mode synchrone
            for k, row in pairs(rows) do
                r:puts( string.format("Name: %s, Age: %s<br/>", row[1], row[2]) )
            end
        else
            r:puts("Database query error: " .. err)
        end
        database:close()
    else
        r:puts("Connexion à la base de données impossible : " .. err)
    end
end

Pour utiliser mod_dbd, spécifiez mod_dbd comme type de base de données, ou laissez le champ vide :

local database = r:dbacquire("mod_dbd")

L'objet database et ses méthodes

L'objet database renvoyé par dbacquire possède les méthodes suivantes :

Sélection normale et requête vers une base de données :

-- Exécution d'une requête et renvoie du nombre d'enregistrements
affectés :
local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")

-- Exécution d'une requête et renvoie du résultat qui peut être utilisé
en mode synchrone ou asynchrone :
local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")

Utilisation de requêtes préparées (recommandé) :

-- Création et exécution d'une requête préparée :
local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` > %u")
if not errmsg then
    local result, errmsg = statement:query(20) -- exécute la requête pour age > 20
end

-- Extrait une requête préparée depuis une directive DBDPrepareSQL :
local statement, errmsg = database:prepared(r, "someTag")
if not errmsg then
    local result, errmsg = statement:select("John Doe", 123) -- injecte les valeurs "John Doe" et 123 dans la requête
end

Echappement de valeurs, fermeture de la base données, etc...

-- Echappe une valeur pour pouvoir l'utiliser dans une requête :
local escaped = database:escape(r, [["'|blabla]])

-- Ferme une base de données et libère les liens vers cette dernière :
database:close()

-- Vérifie si une connexion à une base de données est en service et
opérationnelle :
local connected = database:active()

Travail avec les jeux d'enregistrements renvoyés par les requêtes

Les jeux d'enregistrements renvoyés par db:select ou par des requêtes préparées créées par db:prepare permettent de sélectionner des enregistrements en mode synchrone ou asynchrone, selon le nombre d'enregistrements spécifié :
result(0) sélectionne tous les enregistrements en mode synchrone en renvoyant une table d'enregistrements.
result(-1) sélectionne le prochain enregistrement disponible en mode asynchrone.
result(N) sélectionne l'enregistrement numéro N en mode asynchrone.

-- extrait un jeu d'enregistrements via une requête régulière :
local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")

local rows = result(0) -- sélectionne tous les enregistrements en mode synchrone
local row = result(-1) -- sélectionne le prochain enregistrement disponible en mode asynchrone
local row = result(1234) -- sélectionne l'enregistrement 1234 en mode asynchrone
local row = result(-1, true) -- Lit l'enregistrement suivant en utilisant les noms d'enregistrements comme index.

Il est possible de construire une fonction qui renvoie une fonction itérative permettant de traiter tous les enregistrement en mode synchrone ou asynchrone selon la valeur de l'argument async :

function rows(resultset, async)
    local a = 0
    local function getnext()
        a = a + 1
        local row = resultset(-1)
        return row and a or nil, row
    end
    if not async then
        return pairs(resultset(0))
    else
        return getnext, self
    end
end

local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` > %u")
if not err then
     -- sélectionne des enregistrements en mode asynchrone :
    local result, err = statement:select(20)
    if not err then
        for index, row in rows(result, true) do
            ....
        end
    end

     -- sélectionne des enregistrements en mode synchrone :
    local result, err = statement:select(20)
    if not err then
        for index, row in rows(result, false) do
            ....
        end
    end
end

Fermeture d'une connexion à une base de données

Lorsqu'elles ne sont plus utilisées, les connexions aux bases de données doivent être fermées avec database:close(). Si vous ne les fermez pas manuellement, mod_lua les fermera peut-être en tant que résidus collectés, mais si ce n'est pas le cas, vous pouvez finir pas avoir trop de connexions vers la base de données inutilisées. Les deux mesures suivantes sont pratiquement identiques :

-- Méthode 1 : fermeture manuelle de la connexion
local database = r:dbacquire("mod_dbd")
database:close() -- c'est tout

-- Méthode 2 : on laisse le collecteur de résidus la fermer
local database = r:dbacquire("mod_dbd")
database = nil -- on coupe le lien
collectgarbage() -- fermeture de la connexion par le collecteur de résidus

Précautions à prendre lorsque l'on travaille avec les bases de données

Bien que les fonctions query et run soient toujours disponibles, il est recommandé d'utiliser des requêtes préparées chaque fois que possible, afin d'une part d'optimiser les performances (si votre connexion reste longtemps en vie), et d'autre part minimiser le risque d'attaques par injection SQL. Les fonctions run et query ne doivent être utilisées que lorsque la requête ne contient pas de variables (requête statique). Dans le cas des requêtes dynamiques, utilisez db:prepare ou db:prepared.

Directive LuaAuthzProvider

Description: | Branche une fonction fournisseur d'autorisation dans mod_authz_core
Syntaxe: | LuaAuthzProvider provider_name /path/to/lua/script.lua function_name
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Disponible depuis la version 2.4.3 du serveur HTTP Apache

Lorsqu'une fonction lua a été enregistrée en tant que fournisseur d'autorisation, elle peut être appelée via la directive Require :

LuaRoot "/usr/local/apache2/lua"
LuaAuthzProvider foo authz.lua authz_check_foo
<Location "/">
  Require foo johndoe
</Location>
require "apache2"
function authz_check_foo(r, who)
    if r.user ~= who then return apache2.AUTHZ_DENIED
    return apache2.AUTHZ_GRANTED
end

Directive LuaCodeCache

Description: | Configure le cache de code compilé.
Syntaxe: | LuaCodeCache stat|forever|never
Défaut: | LuaCodeCache stat
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette directive permet de définir le comportement du cache de code en mémoire. La valeur par défaut est stat ; dans ce cas, le script du niveau le plus haut (et pas les scripts inclus) est vérifié à chaque fois que ce fichier est nécessaire, et est rechargé si la date de modification est plus récente que celle du script déjà chargé. Les autres valeurs permettent respectivement de garder le fichier en cache perpétuellement (forever - jamais vérifié ni remplacé), ou de ne jamais le mettre en cache (never).

En général, les valeurs stat et forever sont utilisées pour un serveur en production, et les valeurs stat ou never pour un serveur en développement.

Exemples :

LuaCodeCache stat
LuaCodeCache forever
LuaCodeCache never

Directive LuaHookAccessChecker

Description: | Fournit un point d'entrée pour la phase access_checker du traitement de la requête
Syntaxe: | LuaHookAccessChecker /chemin/vers/lua/script.lua hook_function_name [early|late]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Le troisième argument optionnel est disponible depuis la version 2.3.15 du serveur HTTP Apache.

Ajoute votre fonction d'accroche à la phase access_checker. Une fonction d'accroche access checker renvoie en général OK, DECLINED, ou HTTP_FORBIDDEN.

Ordonnancement

Les arguments optionnels "early" ou "late" permettent de contrôler le moment auquel ce script s'exécute par rapport aux autres modules.

Directive LuaHookAuthChecker

Description: | Fournit un point d'entrée pour la phase auth_checker du traitement de la requête
Syntaxe: | LuaHookAuthChecker /chemin/vers/lua/script.lua hook_function_name [early|late]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Le troisième argument optionnel est disponible depuis la version 2.3.15 du serveur HTTP Apache.

Invoque une fonction lua au cours de la phase auth_checker du traitement de la requête. Cette directive peut s'utiliser pour implémenter une vérification arbitraire de l'authentification et de l'autorisation. Voici un exemple très simple :

require 'apache2'

-- fonction d'accroche authcheck fictive
-- Si la requête ne contient aucune donnée d'authentification, l'en-tête
-- de la réponse est défini et un code 401 est renvoyé afin de demander au
-- navigateur d'effectuer une authentification basique. Si la requête
-- comporte des données d'authentification, elles ne sont pas vraiment
-- consultées, mais on admet la prise en compte de l'utilisateur 'foo' et
-- on la valide. On vérifie ensuite si l'utilisateur est bien 'foo' et on
-- accepte la requête.
function authcheck_hook(r)

   -- recherche des informations d'authentification
   auth = r.headers_in['Authorization']
   if auth ~= nil then
     -- définition d'un utilisateur par défaut
     r.user = 'foo'
   end

   if r.user == nil then
      r:debug("authcheck: user is nil, returning 401")
      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
      return 401
   elseif r.user == "foo" then
      r:debug('user foo: OK')
   else
      r:debug("authcheck: user='" .. r.user .. "'")
      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
      return 401
   end
   return apache2.OK
end

Ordonnancement

Les arguments optionnels "early" ou "late" permettent de contrôler le moment auquel ce script s'exécute par rapport aux autres modules.

Directive LuaHookCheckUserID

Description: | Fournit un point d'entrée pour la phase check_user_id du traitement de la requête
Syntaxe: | LuaHookCheckUserID /chemin/vers/lua/script.lua hook_function_name [early|late]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Le troisième argument optionnel est disponible depuis la version 2.3.15 du serveur HTTP Apache.

...

Ordonnancement

Les arguments optionnels "early" ou "late" permettent de contrôler le moment auquel ce script s'exécute par rapport aux autres modules.

Directive LuaHookFixups

Description: | Fournit un point d'entrée pour la phase de correction du traitement de la requête
Syntaxe: | LuaHookFixups /chemin/vers/lua/script.lua hook_function_name
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Idem LuaHookTranslateName, mais s'exécute durant la phase de correction.

Directive LuaHookInsertFilter

Description: | Fournit un point d'entrée pour la phase insert_filter du traitement de la requête
Syntaxe: | LuaHookInsertFilter /chemin/vers/lua/script.lua hook_function_name
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Non encore implémenté

Directive LuaHookLog

Description: | Permet une insertion dans la phase de journalisation du traitement d'une requête
Syntaxe: | LuaHookLog /path/to/lua/script.lua log_function_name
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Ce dispositif d'insertion simple permet d'exécuter une fonction lorsque httpd entre dans la phase de journalisation du traitement d'une requête. Vous pouvez ainsi ajouter des données à vos propres entrées de journalisation, manipuler les entrées du journal standard avant leur enregistrement ou empêcher l'enregistrement d'une entrée dans le journal. Pour empêcher l'enregistrement normal des entrées du journal, renvoyez simplement apache2.DONE dans votre gestionnaire de journalisation, ou au contraire, renvoyez apache2.OK pour que httpd effectue une journalisation normale.

Exemple :

LuaHookLog "/path/to/script.lua" logger
-- /path/to/script.lua --
function logger(r)
    -- on joue à pile ou face :
    -- Si on obtient 1, on écrit dans notre propre journal Lua et on dit
    -- à httpd de ne pas enregistrer d'entrée dans le journal standard..
    -- Si on obtient 2, on nettoie un peu les données avant que httpd ne
    -- les enregistre dans le journal standard.

    if math.random(1,2) == 1 then
        -- On effectue notre propre journalisation et le journal
    -- standard n'est pas alimenté
        local f = io.open("/foo/secret.log", "a")
        if f then
            f:write("Quelque chose de secret est arrivé à " .. r.uri .. "\n")
            f:close()
        end
        return apache2.DONE -- On dit à httpd de ne rien enregistrer
                --dans le journal standard
    else
        r.uri = r.uri:gsub("somesecretstuff", "") -- nettoie les données
        return apache2.OK -- et httpd doit alors les enregistrer.
    end
end

Directive LuaHookMapToStorage

Description: | Fournit un point d'entrée pour la phase map_to_storage du traitement de la requête
Syntaxe: | LuaHookMapToStorage /chemin/vers/lua/script.lua hook_function_name
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Identique à la directive LuaHookTranslateName, mais s'exécute à la phase map-to-storage du traitement de la requête. Les modules comme mod_cache agissent pendant cette phase, ce qui permet de présenter un exemple intéressant de ce que l'on peut faire ici :

LuaHookMapToStorage "/path/to/lua/script.lua" check_cache
require"apache2"
cached_files = {}

function read_file(filename)
    local input = io.open(filename, "r")
    if input then
        local data = input:read("*a")
        cached_files[filename] = data
        file = cached_files[filename]
        input:close()
    end
    return cached_files[filename]
end

function check_cache(r)
    if r.filename:match("%.png$") then -- Ne concerne que les fichiers PNG
        local file = cached_files[r.filename] -- Vérifie les entrées du cache
        if not file then
            file = read_file(r.filename)  -- Lit le fichier vers le cache
        end
        if file then -- Si le fichier existe, on l'envoie
            r.status = 200
            r:write(file)
            r:info(("%s a été envoyé au client depuis le cache"):format(r.filename))
            return apache2.DONE -- cout-circuite le gestionnaire par défaut des fichiers PNG
        end
    end
    return apache2.DECLINED -- Si nous n'avons rien eu à faire, nous laissons les autres s'en charger
end

Directive LuaHookTranslateName

Description: | Fournit un point d'entrée à la phase du nom de traduction du traitement de la requête
Syntaxe: | LuaHookTranslateName /chemin/vers/lua/script.lua nom_fonction_hook [early|late]
Contexte: | configuration du serveur, serveur virtuel
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Le troisième argument optionnel est disponible depuis la version 2.3.15 du serveur HTTP Apache.

Cette directive permet d'ajouter un point d'entrée (à APR_HOOK_MIDDLE) à la phase du nom de traduction du traitement de la requête. La fonction hook accepte un seul argument, le request_rec, et doit renvoyer un code d'état qui est soit un code d'erreur HTTP, ou une constante définie dans le module apache2 : apache2.OK, apache2.DECLINED, ou apache2.DONE.

Pour ceux qui ne sont pas familiers avec les points d'entrée (hook), en gros, chaque hook sera invoqué jusqu'à ce que l'un d'entre eux renvoie apache2.OK. Si un hook n'effectuer pas la traduction, il doit juste renvoyer apache2.DECLINED. Si le traitement de la requête doit être interrompu, la valeur renvoyée doit être apache2.DONE.

Exemple :

# httpd.conf
LuaHookTranslateName "/scripts/conf/hooks.lua" silly_mapper
-- /scripts/conf/hooks.lua --
require "apache2"
function silly_mapper(r)
    if r.uri == "/" then
        r.filename = "/var/www/home.lua"
        return apache2.OK
    else
        return apache2.DECLINED
    end
end

Contexte

Cette directive ne peut être utilisée ni à l'intérieur d'une section <Directory> ou <Files>, ni dans un fichier htaccess.

Ordonnancement

Les arguments optionnels "early" ou "late" permettent de contrôler le moment auquel ce script s'exécute par rapport aux autres modules.

Directive LuaHookTypeChecker

Description: | Fournit un point d'entrée pour la phase type_checker du traitement de la requête
Syntaxe: | LuaHookTypeChecker /chemin/vers/lua/script.lua hook_function_name
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette directive fournit un point d'entrée pour la phase type_checker du traitement de la requête. Cette phase correspond au moment où la requête se voit assigner un type et un gestionnaire de contenu, et peut donc être utilisée pour modifier le type et le gestionnaire en fonction de l'entrée :

LuaHookTypeChecker "/path/to/lua/script.lua" type_checker
    function type_checker(r)
        if r.uri:match("%.to_gif$") then -- foo.png.to_gif convient
            r.content_type = "image/gif" -- affectation du type image/gif
            r.handler = "gifWizard"      -- force le traitement de la requête par le module gifWizard
            r.filename = r.uri:gsub("%.to_gif$", "") -- corrige le nom du fichier demandé
            return apache2.OK
        end

        return apache2.DECLINED
    end

Directive LuaInherit

Description: | Contrôle la manière dont les sections de configuration parentes sont fusionnées dans les enfants
Syntaxe: | LuaInherit none|parent-first|parent-last
Défaut: | LuaInherit parent-first
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Versions 2.4.0 et supérieures

Par défaut, si des directives LuaHook* se trouvent dans des sections de configuration Directory ou Location qui se chevauchent, les scripts définis dans les sections les plus spécifiques s'exécutent après ceux définis dans les sections plus génériques (LuaInherit parent-first). Vous pouvez inverser cet ordre, ou faire en sorte que le contexte parent ne s'applique pas du tout.

Jusqu'aux versions 2.3.x, le comportement par défaut consistait à ignorer les directives LuaHook* situées dans les sections de configuration parentes.

Directive LuaInputFilter

Description: | Fournit une fonction Lua pour le filtrage en entrée
Syntaxe: | LuaInputFilter filter_name /path/to/lua/script.lua function_name
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Disponible depuis la version 2.4.5 du serveur HTTP Apache

Cette directive permet d'ajouter un filtre en entrée sous la forme d'une fonction Lua. A l'instar des filtres en sorties, les filtres en entrée fonctionnent comme des sous-routines, intervenant dans un premier temps avant l'envoi du contenu des tampons, puis chaque fois qu'un paquet de données doit être transmis à la chaîne, et éventuellement produisant toute donnée à ajouter aux données en entrée. La variable globale bucket contient les paquets de données tels qu'ils sont transmis au script Lua :

LuaInputFilter myInputFilter "/www/filter.lua" input_filter
<Files "*.lua">
  SetInputFilter myInputFilter
</Files>
--[[
    Exemple de filtre en entrée qui convertit toutes les données POST en
    majuscules.
]]--
function input_filter(r)
    print("luaInputFilter called") -- pour débogage
    coroutine.yield() -- attend des paquets de données
    while bucket do -- Pour chaque paquet, faire ...
        local output = string.upper(bucket) -- Convertit toutes les données POST en majuscules
        coroutine.yield(output) -- Envoie les données traitées à la chaîne de filtrage
    end
    -- plus aucune donnée à traiter.
    coroutine.yield("&filterSignature=1234") -- Ajoute une signature à la fin
end

Le filtre en entrée peut interdire ou sauter un filtre s'il est considéré comme indésirable :

function input_filter(r)
    if not good then
        return -- Empêche tout simplement le filtrage et transmet le contenu original
    end
    coroutine.yield() -- attend des paquets de données
    ...               -- insert les filtres ici
end

Voir "Modification de contenu avec les filtres Lua" pour plus de détails.

Directive LuaMapHandler

Description: | Met en correspondance un chemin avec un gestionnaire lua
Syntaxe: | LuaMapHandler modele-uri /chemin/vers/lua/script.lua [nom-fonction]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette directive permet de faire correspondre un modèle d'uri avec une fonction de gestionnaire située dans un fichier spécifique. Elle utilise les expressions rationnelles PCRE pour mettre en correspondance l'uri, et supporte les groupes de correspondance d'interpolation dans le chemin du fichier et le nom de la fonction. Prenez garde aux problèmes de sécurité en écrivant vos expressions rationnelles.

Exemples :

LuaMapHandler "/(\w+)/(\w+)" "/scripts/$1.lua" "handle_$2"

Cette directive va faire correspondre des uri comme /photos/show?id=9 au fichier /scripts/photos.lua, et invoquera la fonction de gestionnaire handle_show au niveau de la vm lua après chargement de ce fichier.

LuaMapHandler "/bingo" "/scripts/wombat.lua"

Cette directive invoquera la fonction "handle" qui est la valeur par défaut si aucun nom de fonction spécifique n'est spécifié.

Directive LuaOutputFilter

Description: | Fournit une fonction Lua pour le filtrage de contenu en sortie
Syntaxe: | LuaOutputFilter filter_name /path/to/lua/script.lua function_name
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_lua
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

>Cette directive permet d'ajouter un filtre en sortie sous la forme d'une fonction Lua. A l'instar des filtres en sorties, les filtres en entrée fonctionnent comme des sous-routines, intervenant dans un premier temps avant l'envoi du contenu des tampons, puis chaque fois qu'un paquet de données doit être transmis à la chaîne, et éventuellement produisant toute donnée à ajouter aux données en sortie. La variable globale bucket contient les paquets de données tels qu'ils sont transmis au script Lua :

LuaOutputFilter myOutputFilter "/www/filter.lua" output_filter
<Files "*.lua">
  SetOutputFilter myOutputFilter
</Files>
--[[
    Exemple de filtre en sortie qui échappe toutes les entités HTML en
    sortie
]]--
function output_filter(r)
    coroutine.yield("(Handled by myOutputFilter)<br/>\n") -- Ajoute des données au début de la sortie,
                                                                -- puis attend des paquets de données à traiter
    while bucket do -- Pour chaque paquet, faire ...
        local output = r:escape_html(bucket) -- Echappe les données en sortie
        coroutine.yield(output) -- Envoie les données traitées à la chaîne
    end
    -- plus aucune donnée à traiter.
end

Comme les filres en entrée, le filtre en sortie peut interdire ou sauter un filtre s'il est considéré comme indésirable :

function output_filter(r)
    if not r.content_type:match("text/html") then
        return -- Empêche tout simplement le filtrage et transmet le contenu original
    end
    coroutine.yield() -- attend des paquets de données
    ...               -- insert les filtres ici
end

Les filtres Lua avec mod_filter

Lorsqu'on utilise un filtre Lua comme fournisseur sous-jacent via la directive FilterProvider, le filtrage ne fonctionnera que si filter-name est identique à provider-name.

Voir "Modification de contenu avec les filtres Lua" pour plus de détails.

Directive LuaPackageCPath

Description: | Ajoute un répertoire au package.cpath de lua
Syntaxe: | LuaPackageCPath /chemin/vers/include/?.soa
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette directive permet d'ajouter un chemin à la liste des chemins de recherche des bibliothèques partagées de lua. Ceci modifie le package.cpath dans les vms lua.

Directive LuaPackagePath

Description: | Ajoute un répertoire au package.path de lua
Syntaxe: | LuaPackagePath /chemin/vers/include/?.lua
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette directive permet d'ajouter un chemin à la liste des chemins de recherche du module lua. Elle suit les mêmes conventions que lua. Ceci modifie le package.path dans les vms lua.

Exemples :

LuaPackagePath "/scripts/lib/?.lua"
LuaPackagePath "/scripts/lib/?/init.lua"

Directive LuaQuickHandler

Description: | Fournit un point d'entrée pour la gestion rapide du traitement de la requête
Syntaxe: | LuaQuickHandler /path/to/script.lua hook_function_name
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette phase s'exécute juste après l'attribution de la requête à un serveur virtuel, et permet d'effectuer certains traitements avant le déroulement des autres phases, ou de servir une requête sans avoir à la traduire, l'associer à un espace de stockage, etc... Comme cette phase s'exécute avant toute autre, les directives telles que <Location> ou <Directory> ne sont pas encore prises en compte, car Les URI n'ont pas encore été entièrement interprétés.

Contexte

Cette directive ne peut être utilisée ni à l'intérieur d'une section <Directory> ou <Files>, ni dans un fichier htaccess.

Directive LuaRoot

Description: | Spécifie le chemin de base pour la résolution des chemins relatifs dans les directives de mod_lua
Syntaxe: | LuaRoot /chemin/vers/un/répertoire
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette directive permet de spécifier le chemin de base qui sera utilisé pour évaluer tous les chemins relatifs dans mod_lua. En l'absence de cette directive, les chemins relatifs sont résolus par rapport au répertoire de travail courant, ce qui ne sera pas toujours approprié pour un serveur.

Directive LuaScope

Description: | Une valeur parmi once, request, conn, thread -- la valeur par défaut est once
Syntaxe: | LuaScope once|request|conn|thread|server [min] [max]
Défaut: | LuaScope once
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | All
Statut: | Expérimental
Module: | mod_lua

Cette directive permet de spécifier la durée de vie de l'interpréteur Lua qui sera utilisé dans ce "répertoire". La valeur par défaut est "once".

once:
utilise l'interpréteur une fois.
request:
utilise l'interpréteur pour traiter tout ce qui est basé sur le même fichier dans la requête, et qui se trouve aussi dans la portée de la requête.
conn:
idem request, mais attaché à connection_rec
thread:
Utilise l'interpréteur pendant toute la durée de vie du thread qui traite la requête (disponible seulement avec les MPMs threadés).
server:
Le comportement est ici différent, car la portée du serveur présente une durée de vie assez longue, et plusieurs threads vont partager le même server_rec. Pour gérer tout ceci, les états lua du serveur sont stockés dans une liste de ressources apr. Les arguments min et max permettent de spécifier les nombres minimaux et maximaux d'états lua à stocker dans la liste.

En général, les portées thread et server sont 2 à 3 fois plus rapides que les autres, car elles n'ont pas besoin de régénérer de nouveaux états Lua à chaque requête (comme c'est le cas avec le MPM event, où même les connexions persistantes utilisent un nouveau thread pour chaque requête). Si vous pensez que vos scripts n'auront pas de problème s'il réutilisent un état, alors les portées thread ou server doivent être utilisées car elles présenteront de meilleures performances. Alors que la portée thread fournira les réponses les plus rapides, la portée server utilisera moins de mémoire car les états sont rassemblés dans des jeux, permettant par exemple à 1000 threads de partager 100 états Lua, ne nécessitant ainsi que 10% de la mémoire requise par la portée thread.


mod_macro - Serveur Apache HTTP Version 2.4

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.

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


mod_md - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_md

Description: | Managing domains across virtual hosts, certificate provisioning via the ACME protocol
Status: | Extension
Module Identifier: | md_module
Source File: | mod_md.c
Compatibility: | Available in version 2.4.30 and later

Summary

This module manages common properties of domains for one or more virtual hosts. Specifically it can use the ACME protocol (RFC Draft) to automate certificate provisioning. These will be configured for managed domains and their virtual hosts automatically. This includes renewal of certificates before they expire. The most famous Certificate Authority currently implementing the ACME protocol is Let's Encrypt.

Warning

This module is experimental. Its behaviors, directives, and defaults are subject to more change from release to release relative to other standard modules. Users are encouraged to consult the "CHANGES" file for potential updates.

Simple configuration example:

TLS in a VirtualHost context

MDomain example.org

<VirtualHost *:443>
    ServerName example.org
    DocumentRoot htdocs/a

    SSLEngine on
    # no certificates specification
</VirtualHost>

This setup will, on server start, contact Let's Encrypt to request a certificate for the domain. If Let's Encrypt can verify the ownership of the domain, the module will retrieve the certificate and its chain, store it in the local file system (see MDStoreDir) and provide it, on next restart, to mod_ssl.

This happens while the server is already running. All other hosts will continue to work as before. While a certificate is not available, requests for the managed domain will be answered with a '503 Service Unavailable'.

Prerequisites

This module requires mod_watchdog to be loaded as well.

Certificate signup and renewal with Let's Encrypt requires your server to be reachable on port 80 (http:) from the outside. The alternative method over port 443 (https:) is currently disabled for security reasons (status from 2018-01-14).

The module will select from the methods offered by Let's Encrypt. If LE decides at one point in the future, to re-enable it again, mod_md will use it when suitable.

But for now, only the port 80 variant is available (termed "http-01"). Only when LE can reach your server on port 80 will mod_md work for you. For now, at least.

If you do not want to offer any sites on port 80 any more, you may leave it open and redirect all requests to your https: sites instead. Use the MDRequireHttps described below to do that in a convenient fashion. This will continue to answer http: challenges from Let's Encrypt.

MDBaseServer Directive

Description: | Control if base server may be managed or only virtual hosts.
Syntax: | MDBaseServer on|off
Default: | MDBaseServer off
Context: | server config
Status: | Extension
Module: | mod_md

Controls if the base server, the one outside all VirtualHosts should be managed by mod_md or not. Default is to not do this, for the very reason that it may have confusing side-effects. It is recommended that you have virtual hosts for all managed domains and do not rely on the global, fallback server configuration.

MDCAChallenges Directive

Description: | Type of ACME challenge used to prove domain ownership.
Syntax: | MDCAChallenges name [ name ... ]
Default: | MDCAChallenges tls-sni-01 http-01
Context: | server config
Status: | Extension
Module: | mod_md

Sets challenge types and their execution order when proving domain ownership. The names are protocol specific. The current ACME protocol version implemented by Let's Encrypt defines two challenge types that are supported by mod_md. By default, it will try the one on port 443 when available.

MDCertificateAgreement Directive

Description: | The URL of the Terms-of-Service document, that the CA server requires you to accept.
Syntax: | MDCertificateAgreement url-of-terms-of-service
Context: | server config
Status: | Extension
Module: | mod_md

When you use mod_md to obtain a certificate, you become a customer of the CA (e.g. Let's Encrypt). That means you need to read and agree to their Terms of Service, so that you understand what they offer and what they might exclude or require from you. mod_md cannot, by itself, agree to such a thing.

In case of Let's Encrypt, their current Terms of Service are here. Those terms might (and probably will) change over time. So, the certificate renewal might require you to update this agreement URL.

Example

MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
MDomain example.org www.example.org mail.example.org

MDCertificateAuthority Directive

Description: | The URL of the ACME Certificate Authority service.
Syntax: | MDCertificateAuthority url
Default: | MDCertificateAuthority https://acme-v01.api.letsencrypt.org/directory
Context: | server config
Status: | Extension
Module: | mod_md

The URL where the CA offers its service.

Let's Encrypt offers, right now, two such URLs. One for the real certificates and one for testing (their staging area, at https://acme-staging.api.letsencrypt.org/directory). In order to have mod_md use this testing service, configure your server like this:

LE Staging Setup

MDCertificateAuthority https://acme-staging.api.letsencrypt.org/directory
MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf

MDCertificateProtocol Directive

Description: | The protocol to use with the Certificate Authority.
Syntax: | MDCertificateProtocol protocol
Default: | MDCertificateProtocol ACME
Context: | server config
Status: | Extension
Module: | mod_md

Specifies the protocol to use. Currently, only ACME is supported.

MDDriveMode Directive

Description: | Control when it is allowed to obtain/renew certificates.
Syntax: | MDDriveMode always|auto|manual
Default: | MDDriveMode auto
Context: | server config
Status: | Extension
Module: | mod_md

In 'auto' mode, mod_md will drive a Managed Domain's properties (e.g. certificate management) whenever necessary. When a MD is not used in any virtual host, the module will do nothing. When a certificate is missing, it will try to get one. When a certificate expires soon (see MDRenewWindow), it will renew it.

In 'manual' mode, it is your duty to do all this. The module will provide the existing certificate to mod_ssl, if available. But it will not contact the CA for signup/renewal. This can be useful in clustered setups where you want just one node to perform the driving.

The third mode 'always' is like 'auto', with the difference that mod_md will not check if the MD is actually used.

MDHttpProxy Directive

Description: | Define a proxy for outgoing connections.
Syntax: | MDHttpProxy url
Context: | server config
Status: | Extension
Module: | mod_md

Use a http proxy to connect to the MDCertificateAuthority. Define this if your webserver can only reach the internet with a forward proxy.

MDMember Directive

Description: | Additional hostname for the managed domain.
Syntax: | MDMember hostname
Context: | server config
Status: | Extension
Module: | mod_md

Instead of listing all dns names on the same line, you may use MDMember to add such names to a managed domain.

Example

<MDomainSet example.org>
    MDMember www.example.org
    MDMember mail.example.org
</MDomainSet example.org>

If you use it in the global context, outside a specific MD, you can only specify one value, 'auto' or 'manual' as the default for all other MDs. See MDomain for a description of these special values.

MDMembers Directive

Description: | Control if the alias domain names are automatically added.
Syntax: | MDMembers auto|manual
Default: | MDMembers auto
Context: | server config
Status: | Extension
Module: | mod_md

Defines if the ServerName and ServerAlias values of a VirtualHost are automatically added to the members of a Managed Domain or not.

MDMustStaple Directive

Description: | Control if new certificates carry the OCSP Must Staple flag.
Syntax: | MDMustStaple on|off
Default: | MDMustStaple off
Context: | server config
Status: | Extension
Module: | mod_md

Defines if newly requested certificate should have the OCSP Must Staple flag set or not. If a certificate has this flag, the server is required to send a OCSP stapling response to every client. This only works if you configure mod_ssl to generate this (see SSLUseStapling and friends).

MDNotifyCmd Directive

Description: | Run a program when Managed Domain are ready.
Syntax: | MDNotifyCmd path
Context: | server config
Status: | Extension
Module: | mod_md

The configured executable is run when Managed Domains have signed up or renewed their certificates. It is given the names of the processed MDs as arguments. It should return status code 0 to indicate that it has run successfully.

MDomain Directive

Description: | Define list of domain names that belong to one group.
Syntax: | MDomain dns-name [ other-dns-name... ] [auto|manual]
Context: | server config
Status: | Extension
Module: | mod_md

All the names in the list are managed as one Managed Domain (MD). mod_md will request one single certificate that is valid for all these names. This directive uses the global settings (see other MD directives below). If you need specific settings for one MD, use the <MDomainSet>.

There are 2 additional settings that are necessary for a Managed Domain: ServerAdmin and MDCertificateAgreement. The mail address of ServerAdmin is used to register at the CA (Let's Encrypt by default). The CA may use it to notify you about changes in its service or status of your certificates.

The second setting, MDCertificateAgreement, is the URL of the Terms of Service of the CA. When you configure the URL, you confirm that you have read and agree to the terms described in the linked document. Before you do that, the CA will not hand out certificates to you.

Example

ServerAdmin mailto:admin@example.org
MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
MDomain example.org www.example.org

<VirtualHost *:443>
    ServerName example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

<VirtualHost *:443>
    ServerName www.example.org
    DocumentRoot htdocs/www

    SSLEngine on
</VirtualHost>

There are two special names that you may use in this directive: 'manual' and 'auto'. This determines if a Managed Domain shall have exactly the name list as is configured ('manual') or offer more convenience. With 'auto' all names of a virtual host are added to a MD. Conventiently, 'auto' is also the default.

Example

MDomain example.org

<VirtualHost *:443>
    ServerName example.org
    ServerAlias www.example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

MDomain example2.org auto

<VirtualHost *:443>
    ServerName example2.org
    ServerAlias www.example2.org
    ...
</VirtualHost>

In this example, the domain 'www.example.org' is automatically added to the MD 'example.org'. Similarly for 'example2.org' where 'auto' is configured explicitly. Whenever you add more ServerAlias names to this virtual host, they will be added as well to the Manged Domain.

If you prefer to explicitly declare all the domain names, use 'manual' mode. An error will be logged if the names do not match with the expected ones.

<MDomainSet> Directive

Description: | Container for directives applied to the same managed domains.
Syntax: | <MDomainSet dns-name [ other-dns-name... ]>...</MDomainSet>
Context: | server config
Status: | Extension
Module: | mod_md

This directive allows you to define a Managed Domain (MD) with specific settings, different from the global MD* ones. For example, you can have such an MD use another CA then Let's Encrypt, have its unique renewal duration etc.

Example

<MDomainSet sandbox.example.org>
    MDCertificateAuthority   https://someotherca.com/ACME
    MDCertificateAgreement   https://someotherca.com/terms/v_1.02.pdf
</MDomainSet>

This is a specialized version of MDomain, it should be used only when a fine grained configuration is required. MDomain is the suggested choice for the general use case.

MDPortMap Directive

Description: | Map external to internal ports for domain ownership verification.
Syntax: | MDPortMap map1 [ map2 ]
Default: | MDPortMap 80:80 443:443
Context: | server config
Status: | Extension
Module: | mod_md

The ACME protocol provides two method to verify domain ownership: one that uses port 80 and one for port 443. If your server is not reachable by at least one of the two, ACME will not work for you.

mod_md will look at your server configuration and try to figure out which of those are available. Then it can select the proper ACME challenge to create a certificate for your site.

However if you have some fancy port forwarding in place, your server may be reachable from the Internet on port 443, but the local port that httpd uses is another one. Your server might only listen on ports 5001 and 5002, but be reached on ports 443 and 80. How should mod_md figure that one out?

With MDPortMap you can tell it which 'Internet port' corresponds to which local port.

Example

MDPortMap 80:- 443:5002

This example says that the server is not reachable on port 80 from the outside, but local port 5002 is the one responding to https: requests.

MDPrivateKeys Directive

Description: | Set type and size of the private keys generated.
Syntax: | MDPrivateKeys type [ params... ]
Default: | MDPrivateKeys RSA 2048
Context: | server config
Status: | Extension
Module: | mod_md

Defines what kind of private keys are generated for a managed domain and with what parameters. The only supported type right now is 'RSA' and the only parameter it takes is the number of bits used for the key.

The current (2017) recommendation is at least 2048 bits and a smaller number is not accepted here. Higher numbers offer longer security, but are computationally more expensive, e.g. increase the load on your server. That might or might not be an issue for you.

Other key types will be defined in the future.

Example

MDPrivateKeys RSA 3072

Please note that this setting only has an effect on new keys. Any existing private key you have remains unaffected. Also, this only affects private keys generated for certificates. ACME account keys are unaffected by this.

MDRenewWindow Directive

Description: | Control when a certificate will be renewed.
Syntax: | MDRenewWindow duration
Default: | MDRenewWindow 33%
Context: | server config
Status: | Extension
Module: | mod_md

If the validity of the certificate falls below duration, mod_md will get a new signed certificate.

Normally, certificates are valid for around 90 days and mod_md will renew them the earliest 33% of their complete lifetime before they expire (so for 90 days validity, 30 days before it expires). If you think this is not what you need, you can specify either the exact time, as in:

Example

# 21 days before expiry
MDRenewWindow 21d
# 30 seconds (might be close)
MDRenewWindow 30s
# 10% of the cert lifetime
MDRenewWindow 10%

When in auto drive mode, the module will check every 12 hours at least what the status of the managed domains is and if it needs to do something. On errors, for example when the CA is unreachable, it will initially retry after some seconds. Should that continue to fail, it will back off to a maximum interval of hourly checks.

MDRequireHttps Directive

Description: | Redirects http: traffic to https: for Managed Domains.
Syntax: | MDRequireHttps off|temporary|permanent
Default: | MDRequireHttps off
Context: | server config
Status: | Extension
Module: | mod_md

This is a convenience directive to ease http: to https: migration of your Managed Domains. With:

Example

MDRequireHttps temporary

you announce that you want all traffic via http: URLs to be redirected to the https: ones, for now. This is safe and you can remove this again at any time.

The following has consequences: if you want client to no longer use the http: URLs, configure:

Permanent (for at least half a year!)

MDRequireHttps permanent

This does two things:

  1. All request to the http: resources are redirected to the same url with the https: scheme using the 301 status code. This tells clients that this is intended to be forever and the should update any links they have accordingly.
  2. All answers to https: requests will carry the header Strict-Transport-Security with a life time of half a year. This tells the browser that it never (for half a year) shall use http: when talking to this domain name. Browsers will, after having seen this, refuse to contact your unencrypted site. This prevents malicious middleware to downgrade connections and listen/manipulate the traffic. Which is good. But you cannot simply take it back again.

You can achieve the same with mod_alias and some Redirect configuration, basically. If you do it yourself, please make sure to exclude the paths /.well-known/* from your redirection, otherwise mod_md might have trouble signing on new certificates.

If you set this globally, it applies to all managed domains. If you want it for a specific domain only, use:

Example

<MDomainSet xxx.yyy>
  MDRequireHttps temporary
</MDomainSet>

MDStoreDir Directive

Description: | Path on the local file system to store the Managed Domains data.
Syntax: | MDStoreDir path
Default: | MDStoreDir md
Context: | server config
Status: | Extension
Module: | mod_md

Defines where on the local file system the Managed Domain data is stored. This is an absolute path or interpreted relative to the server root. The default will create a directory 'md' in your server root.

If you move this and have already data, be sure to move/copy the data first to the new location, reconfigure and then restart the server. If you reconfigure and restart first, the server will try to get new certificates that it thinks are missing.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_mime - Serveur Apache HTTP Version 2.4

Module Apache mod_mime

Description: | Associe les extensions des fichiers demandés avec l'action déclenchée par ces fichiers et avec leur contenu (type MIME, langue, jeu de caractère et codage)
Statut: | Base
Identificateur de Module: | mime_module
Fichier Source: | mod_mime.c

Sommaire

Ce module permet d'assigner des métadonnées aux contenus sélectionnés pour une réponse HTTP, en associant des modèles d'URI ou de noms de fichiers aux valeurs des métadonnées. Par exemple, les extensions de noms de fichiers définissent souvent le type de médium Internet, la langue, le jeu de caractères et le codage du contenu. Ces informations sont relayées par les messages HTTP véhiculant ces contenus, et utilisées au cours de la négociation de contenu lors de la sélection des différentes possibilités, de manière à ce que les préférences des utilisateurs soient respectées lors du choix d'un contenu à servir parmi plusieurs autres contenus. Voir mod_negotiation pour plus d'informations à propos de la négociation de contenu.

Les directives AddCharset, AddEncoding, AddLanguage et AddType permettent d'associer des extensions de fichiers aux métadonnées de ces fichiers. Elles définissent respectivement le jeu de caractères, le codage du contenu, la langue du contenu et le type de médium (content-type) des documents. La directive TypesConfig permet de spécifier un fichier qui contient lui-même des associations entre extensions et types de media.

De plus, mod_mime peut définir le gestionnaire et les filtres qui sont à l'origine du contenu et le traitent. Les directives AddHandler, AddOutputFilter, et AddInputFilter permettent de contrôler les modules ou les scripts qui vont servir le document. La directive MultiviewsMatch permet à mod_negotiation de déterminer les extensions de fichiers à inclure lors des tests de correspondances multivues.

Alors que mod_mime associe des métadonnées avec des extensions de fichiers, le serveur de base core fournit des directives permettant d'associer tous les fichiers d'un conteneur donné (par exemple <Location>, <Directory>, ou <Files>) avec des métadonnées particulières. Parmi ces directives, on trouve ForceType, SetHandler, SetInputFilter, et SetOutputFilter. Les directives du serveur de base l'emportent sur toute directive d'association d'extensions de noms de fichiers définie par mod_mime.

Notez que la modification des métadonnées d'un fichier ne modifie pas la valeur de l'en-tête Last-Modified. Ainsi, certaines copies de documents préalablement mises en cache peuvent encore être utilisées par un client ou un mandataire avec les anciens en-têtes. Si vous modifiez les métadonnées (langue, type de contenu, jeu de caractère ou codage), vous devez donc enregistrer une modification du fichier concerné (afin de mettre à jour sa date de dernière modification), pour être sûr que tous les visiteurs recevront le documents avec les en-têtes corrects.

Traitement des bugs

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

Voir aussi

  • MimeMagicFile
  • AddDefaultCharset
  • ForceType
  • SetHandler
  • SetInputFilter
  • SetOutputFilter

Fichiers avec extensions multiples

Les fichiers peuvent posséder plusieurs extensions dont l'ordre est normalement sans importance. Par exemple, si le fichier welcome.html.fr est associé au type de contenu text/html et à la langue française, le fichier welcome.fr.html possèdera exactement les même métadonnées. Si le fichier possède plusieurs extensions associées au même type de métadonnée, c'est celle de ces extensions la plus à droite qui sera utilisée, excepté pour ce qui concerne les langues et les codages de contenu. Par exemple, si .gif est associé au type de médium image/gif, et .html au type de médium text/html, le fichier welcome.gif.html sera associé au type de médium text/html.

Les Languages et les codages de contenu sont traités de manière cumulative, car il est possible d'assigner plusieurs langues ou codages à une ressource particulière. Par exemple, le fichier welcome.html.en.de sera servi avec les en-têtes Content-Language: en, de et Content-Type: text/html.

Des précautions doivent être prises lorsqu'un fichier avec extensions multiples est associé à la fois à un type de médium et à un gestionnaire. En général, cela impliquera la gestion de la requête par le module associé au gestionnaire. Par exemple, si l'extension .imap est associée au gestionnaire imap-file (du module mod_imagemap), et si l'extension .html est associée au type de médium text/html, le fichier world.imap.html sera à la fois associé au gestionnaire imap-file et au type de médium text/html. Pour son traitement, c'est le gestionnaire imap-file qui sera utilisé, et il sera donc traité en tant que fichier imagemap.

Si vous préférez que seule la dernière partie d'un nom de fichier séparée du reste du nom par un point soit associée à une métadonnée particulière, n'utilisez pas les directives Add*. Par exemple, si vous souhaitez que le fichier foo.html.cgi soit traité en tant que script CGI, mais pas le fichier bar.cgi.html, alors, au lieu d'utiliser AddHandler cgi-script .cgi, utilisez plutôt :

Configuration du gestionnaire en se basant seulement sur la dernière extension

<FilesMatch "[^.]+\.cgi$">
  SetHandler cgi-script
</FilesMatch>

Codage du contenu

Un fichier d'un type de médium particulier peut être également codé d'une certaine manière pour simplifier sa transmission sur Internet. Alors que cela concerne en général la compression, comme gzip, il peut aussi s'agir de chiffrement, comme pgp ou d'un codage comme UUencoding, qui est conçu pour transmettre un fichier binaire sous un format ASCII (texte).

La RFC HTTP/1.1, section 14.11 stipule à ce titre :

Le champ d'en-tête Content-Encoding de l'entité est utilisé en tant que modificateur du type de médium. Lorsqu'il est présent, sa valeur indique quels codages de contenu additionnels ont été appliqués au corps de l'entité, et ainsi quels mécanismes de décodage doivent être appliqués afin de retrouver le type de médium référencé par le champ d'en-tête Content-Type. Le codage de contenu est principalement utilisé pour permettre la compression d'un document sans perdre l'information concernant le type de médium sous-jacent.

En utilisant plusieurs extensions (voir la section ci-dessus à propos des extensions de fichiers multiples), vous pouvez indiquer qu'un fichier est d'un type, particulier, et possède aussi un codage particulier.

Considérons par exemple un fichier contenant un document Microsoft Word et compressé par pkzip pour réduire sa taille. Si l'extension .doc est associée au type de fichier Microsoft Word, et si l'extension .zip est associée au codage de fichier pkzip, alors le fichier Resume.doc.zip sera identifié comme document Word compressé par pkzip.

Apache joint un en-tête Content-encoding à la ressource afin d'informer le navigateur client à propos de la méthode de codage.

Content-encoding: pkzip

Jeux de caractères et langues

En plus du type de fichier et du codage, un autre élément important d'information est la langue dans laquelle le document est écrit, et avec quel jeu de caractères le contenu du fichier doit être affiché. Par exemple, un document peut être écrit en alphabet vietnamien ou cyrillique, et doit être affiché en conséquence. Cette information est également transmise via des en-têtes HTTP.

Les jeu de caractères, langue, codage et type MIME sont tous utilisés au cours du processus de négociation de contenu (voir mod_negotiation) afin de déterminer quel document servir au client, lorsque plusieurs choix sont possibles en fonction du jeu de caractères, de la langue, du codage ou du type MIME. Toutes les associations d'extensions de noms de fichiers créées via les directives AddCharset, AddEncoding, AddLanguage et AddType (ainsi que les associations d'extensions listées dans le fichier défini par la directive MimeMagicFile), participent à ce processus de sélection. Les extensions de noms de fichiers qui n'ont été associés que par des directives AddHandler, AddInputFilter ou AddOutputFilter, peuvent être incluses ou exclues du processus de sélection en utilisant la directive MultiviewsMatch.

Jeu de caractères

Pour transmettre cette information supplémentaire, Apache peut ajouter un en-tête Content-Language, afin de spécifier la langue dans laquelle le document est écrit, et peut ajouter des informations additionnelles à l'en-tête Content-Type pour indiquer le jeu de caractères particulier qui doit être utilisé pour restituer correctement le document.

Content-Language: en, fr Content-Type: text/plain; charset=ISO-8859-1

La langue est spécifiée via son abréviation en deux lettres. Le jeu de caractères est le nom du jeu de caractères particulier qui doit être utilisé.

Directive AddCharset

Description: | Associe les extensions de noms de fichiers spécifiées au jeu de caractères spécifié
Syntaxe: | AddCharset jeu-car extension [extension] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive AddCharset permet d'associer les extensions de noms de fichiers spécifiées au jeu de caractères spécifié (le nom enregistré sur l'Internet d'un codage de caractères donné). jeu-car est le paramètre jeu de caractères du type de médium pour les ressources dont le nom de fichier contient extension. Cette association est ajoutée à toutes les autres déjà en vigueur, et écrase toute association préexistante pour la même extension.

Exemple

AddLanguage ja .ja
AddCharset EUC-JP .euc
AddCharset ISO-2022-JP .jis
AddCharset SHIFT_JIS .sjis

Avec cet exemple, le document xxxx.ja.jis sera traité en tant que document japonais dont le jeu de caractère est ISO-2022-JP (idem pour le document xxxx.jis.ja). La directive AddCharset sert à la fois à informer le client sur le codage des caractères du document afin que ce dernier puisse être interprété et affiché correctement, et à la négociation de contenu, au cours de laquelle le serveur décide lequel parmi plusieurs documents possibles il renvoie au client en fonction des préférences de ce dernier en matière de jeu de caractères.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial. Les noms de fichiers peuvent posséder plusieurs extensions, et l'argument extension sera comparé à chacune d'entre elles.

Voir aussi

  • mod_negotiation
  • AddDefaultCharset

Directive AddEncoding

Description: | Associe les extensions de noms de fichiers données au type de codage spécifié
Syntaxe: | AddEncoding codage extension [extension] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive AddEncoding permet d'associer les extensions de noms de fichiers données au codage de contenu HTTP spécifié. codage est le codage de contenu HTTP à ajouter à la valeur du champ d'en-tête Content-Encoding pour les documents possédant l'extension spécifiée. Cette association est ajoutée à toutes les autres déjà en vigueur, et écrase toute association préexistante pour la même extension.

Exemple

AddEncoding x-gzip .gz
AddEncoding x-compress .Z

Avec cet exemple, les noms de fichiers possédant l'extension .gz seront marqués comme codés à l'aide du codage x-gzip, et les noms de fichiers possédant l'extension .Z comme codés avec x-compress.

Les clients anciens n'acceptent que x-gzip et x-compress, bien que les standards stipulent qu'ils sont respectivement équivalents à gzip et compress. Apache effectue ses comparaisons de codages de contenu en ignorant tout préfixe x-. Lorsqu'il répond avec un codage, Apache utilise l'une ou l'autre forme (c'est à dire x-foo ou foo) selon les besoins du client. Si le client n'a pas besoin d'une forme particulière, Apache utilisera la forme employée par la directive AddEncoding. Pour résumer, vous devez toujours utiliser x-gzip et x-compress pour ces deux codages spécifiques. Certains codages plus récents, comme deflate, doivent être spécifiés sans le préfixe x-.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial. Les noms de fichiers peuvent posséder plusieurs extensions, et l'argument extension sera comparé à chacune d'entre elles.

Directive AddHandler

Description: | Associe les extensions de noms de fichiers données au gestionnaire spécifié
Syntaxe: | AddHandler nom-gestionnaire extension [extension] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

Les fichiers dont le nom a pour extension extension seront servis par le nom-gestionnaire spécifié. Cette association est ajoutée à toutes les autres déjà en vigueur, et écrase toute association préexistante pour la même extension. Par exemple, pour associer les scripts CGI avec l'extension de fichier .cgi, vous pouvez utiliser :

AddHandler cgi-script .cgi

Une fois cette ligne insérée dans votre fichier httpd.conf, tout fichier possédant l'extension .cgi sera traité en tant que programme CGI.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial. Les noms de fichiers peuvent posséder plusieurs extensions, et l'argument extension sera comparé à chacune d'entre elles.

Voir aussi

  • SetHandler

Directive AddInputFilter

Description: | Associe les extensions de noms de fichiers aux filtres spécifiés qui traiteront les requêtes clients
Syntaxe: | AddInputFilter filtre[;filtre...] extension [extension] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive AddInputFilter permet d'associer l'extension de nom de fichier extension aux filtres spécifiés qui traiteront les requêtes clients et les entrées POST à leur réception par le serveur. Ceci s'ajoute à toute définition de filtre préexistante, y compris la directive SetInputFilter. Cette association est ajoutée à toutes les autres déjà en vigueur, et écrase toute association préexistante pour la même extension.

Si plusieurs filtres sont spécifiés, ils doivent être séparés par des points-virgules et inscrits dans l'ordre selon lequel ils devront traiter le contenu. L'argument filtre est insensible à la casse.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial. Les noms de fichiers peuvent posséder plusieurs extensions, et l'argument extension sera comparé à chacune d'entre elles.

Voir aussi

  • RemoveInputFilter
  • SetInputFilter

Directive AddLanguage

Description: | Associe l'extension de nom de fichier donnée à la langue spécifié
Syntaxe: | AddLanguage symbole-langue extension [extension] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive AddLanguage permet d'associer l'extension de nom de fichier donnée à la langue spécifiée. Les fichiers dont l'extension correspond à la valeur de l'argument extension se voient attribuer la valeur de l'argument symbole-langue comme en-tête HTTP Content-Language en accord avec les identifiants de langues définis par la RFC 3066. Cette directive l'emporte sur toute association préexistante pour la même extension.

Exemple

AddEncoding x-compress .Z
AddLanguage en .en
AddLanguage fr .fr

Avec cet exemple, le document xxxx.en.Z sera traité en tant que document compressé de langue anglaise (idem pour le document xxxx.Z.en). Bien que la langue soit fournie au client, le navigateur n'utilise habituellement pas cette information. La directive AddLanguage est principalement utilisée au cours de la négociation de contenu, où le serveur choisit d'envoyer un document parmi plusieurs documents possibles en fonction de la préférence du client en matière de langue.

Si une extension fait l'objet de plusieurs associations de langues, c'est la dernière qui sera utilisée. Ainsi, dans le cas suivant,

AddLanguage en .en
AddLanguage en-gb .en
AddLanguage en-us .en

les documents possédant l'extension .en seront traités en tant que documents de langue en-us.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial. Les noms de fichiers peuvent posséder plusieurs extensions, et l'argument extension sera comparé à chacune d'entre elles.

Voir aussi

  • mod_negotiation

Directive AddOutputFilter

Description: | Associe les extensions de noms de fichiers aux filtres spécifiés qui traiteront les réponses en provenance du serveur
Syntaxe: | AddOutputFilter filtre[;filtre...] extension [extension] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive AddOutputFilter permet d'associer l'extension de nom de fichier définie par l'argument extension aux filtres qui traiteront les réponses en provenance du serveur avant de les envoyer au client. Ces filtres s'ajoutent à tout filtre défini par d'autres directives comme SetOutputFilter et AddOutputFilterByType. Cette association est fusionnée avec toute autre association en vigueur, et l'emporte sur toute association préexistante pour la même extension.

Avec l'exemple suivant, tous les fichiers .shtml seront traités en tant qu'inclusions côté serveur (SSI), et la sortie sera compressée à l'aide du module mod_deflate.

AddOutputFilter INCLUDES;DEFLATE shtml

Si plusieurs filtres sont spécifiés, ils doivent être séparés par des points-virgules et inscrits dans l'ordre selon lequel il devront traiter le contenu. L'argument filtre est insensible à la casse.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial. Les noms de fichiers peuvent posséder plusieurs extensions, et l'argument extension sera comparé à chacune d'entre elles.

Notez que toute définition de filtres via la directive AddOutputFilter remplace toutes les définitions précédentes effectuées via cette même directive.

# Filtre spécifié "DEFLATE"
AddOutputFilter DEFLATE shtml
<Location "/foo">
  # Filtre spécifié "INCLUDES", remplace "DEFLATE"
  AddOutputFilter INCLUDES shtml
</Location>
<Location "/bar">
  # Filtre spécifié "INCLUDES;DEFLATE", remplace "DEFLATE"
  AddOutputFilter INCLUDES;DEFLATE shtml
</Location>
<Location "/bar/baz">
  # Filtre spécifié "BUFFER", remplace "INCLUDES;DEFLATE"
  AddOutputFilter BUFFER shtml
</Location>
<Location "/bar/baz/buz">
  # Pas de filtre spécifié, suppression de "BUFFER"
  RemoveOutputFilter shtml
</Location>

Voir aussi

  • RemoveOutputFilter
  • SetOutputFilter

Directive AddType

Description: | Associe les extensions de noms de fichiers au type de contenu spécifié
Syntaxe: | AddType type-médium extension [extension] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive AddType permet d'associer les extensions de noms de fichiers données au type de contenu spécifié. type-médium est le Type MIME à utiliser pour les fichiers dont le nom possède l'extension extension. Cette association s'ajoute à toute autre association en vigueur, et l'emporte sur toute association préexistante pour la même extension.

Plutôt que d'éditer directement le fichier TypesConfig, il est recommandé d'utiliser la directive AddType pour ajouter de nouveaux types de médias.

Exemple

AddType image/gif .gif

Ou, pour spécifier plusieurs extensions dans une seule directive :

Exemple

AddType image/jpeg jpeg jpg jpe

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial. Les noms de fichiers peuvent posséder plusieurs extensions, et l'argument extension sera comparé à chacune d'entre elles.

Il est possible d'obtenir un effet similaire à celui de la directive LanguagePriority du module mod_negotiation en qualifiant un type de média avec qs :

Exemple

AddType application/rss+xml;qs=0.8 .xml

Ceci peut s'avérer utile dans certaines situations, par exemple lorsqu'un client qui a ajouté un en-tête Accept: */* à sa requête n'est pas en mesure de traiter le contenu renvoyé par le serveur.

À la base, cette directive configure le type de contenu généré pour les fichiers statiques servis à partir du système de fichiers. Dans le cas des ressources autres que les fichiers statiques pour lesquelles le générateur de la réponse spécifie en général un Content-Type, cette directive n'a aucun effet.

Note

Si aucun gestionnaire n'est explicitement défini pour une requête, le type de contenu spécifié sera aussi utilisé comme nom du gestionnaire.

Lorsqu'aucune directive comme SetHandler ou AddHandler ne s'applique à une requête, le nom de gestionnaire interne normalement défini par une de ces directives est en fait défini par le type de contenu spécifié par la présente directive.

Pour des raisons historiques, certains modules tiers comme mod_php peuvent adopter ce type de comportement pour prendre en compte la requête concernée.

Il est conseillé d'éviter les configurations qui reposent sur de tels types "synthétiques". En outre, les configurations qui limitent l'accès aux directives SetHandler ou AddHandler doivent aussi limiter l'accès à la directive AddType.

Voir aussi

  • ForceType
  • mod_negotiation

Directive DefaultLanguage

Description: | Définit un symbole de langue par défaut à affecter au champ d'en-tête Content-Language pour toutes les ressources dans le contexte courant auxquelles aucun symbole de langue n'a été associé.
Syntaxe: | DefaultLanguage symbole-langue
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive DefaultLanguage permet d'indiquer à Apache que toutes les ressources du contexte courant (par exemple, toutes les ressources concernées par le conteneur <Directory> courant) qui ne possèdent pas d'extension de langue explicite (comme .fr ou .de tel que défini par la directive AddLanguage), verront leur en-tête HTTP Content-Language affecté de la langue symbole-langue. Ceci permet de marquer des arborescences de répertoires entières comme contenant des documents en français, par exemple, sans avoir à renommer chaque fichier. Notez qu'à la différence de l'utilisation des extensions pour spécifier des langues, DefaultLanguage ne permet de spécifier qu'une seule langue.

Si aucune directive DefaultLanguage n'est en vigueur, et si un fichier ne possède pas d'extension configurée par la directive AddLanguage, aucun champ d'en-tête Content-Language ne sera généré.

Exemple

DefaultLanguage en

Voir aussi

  • mod_negotiation

Directive ModMimeUsePathInfo

Description: | Indique à mod_mime de traiter les éléments de path_info en tant que parties du nom de fichier
Syntaxe: | ModMimeUsePathInfo On|Off
Défaut: | ModMimeUsePathInfo Off
Contexte: | répertoire
Statut: | Base
Module: | mod_mime

La directive ModMimeUsePathInfo permet de combiner le nom de fichier avec la partie path_info de l'URL pour appliquer les directives mod_mime à la requête. La valeur par défaut est Off - situation dans laquelle l'élément path_info est ignoré.

L'utilisation de cette directive est conseillée si vous utilisez un système de fichiers virtuel.

Exemple

ModMimeUsePathInfo On

Considérons une requête pour /index.php/foo.shtml, mod_mime ne traitera pas la requête entrante comme /index.php/foo.shtml et les directives comme AddOutputFilter INCLUDES .shtml ajouteront le filtre INCLUDES à la requête. Si la directive ModMimeUsePathInfo n'est pas définie, le filtre INCLUDES ne sera pas ajouté. Le fonctionnement sera identique dans le cas des chemins virtuels, tels que ceux définis par la directive <Location>

Voir aussi

  • AcceptPathInfo

Directive MultiviewsMatch

Description: | Les types de fichiers qui seront inclus lors d'une recherche de correspondance de fichier avec les vues multiples (MultiViews)
Syntaxe: | MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters]
Défaut: | MultiviewsMatch NegotiatedOnly
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive MultiviewsMatch permet trois comportements différents pour la fonctionnalité Multiviews du module mod_negotiation. Les vues multiples permettent d'associer une requête pour un fichier, par exemple index.html, à toute extension négociée s'ajoutant à la requête de base, par exemple index.html.en, index.html.fr, ou index.html.gz.

L'option NegotiatedOnly implique que toute extension s'ajoutant au nom de base doit correspondre à une extension de mod_mime reconnue pour la négociation de contenu, par exemple Charset, Content-Type, Language, ou Encoding. C'est la valeur d'option par défaut, et la contrainte la plus stricte dont les effets de bord inattendus sont les moins nombreux.

Pour inclure des extensions associées avec des gestionnaires et/ou des filtres, définissez la directive MultiviewsMatch avec les mots-clés Handlers, Filters, ou les deux. Si tous les autres facteurs sont égaux, c'est le fichier de plus petite taille qui sera servi ; par exemple, si le choix doit s'opérer entre index.html.cgi de 500 octets et index.html.pl de 1000 octets, c'est le fichier .cgi qui l'emportera dans cet exemple. Les utilisateurs de fichiers .asis auront avantage à utiliser l'option Handler, si les fichiers .asis sont associés au gestionnaire asis-handler.

Vous pouvez enfin autoriser l'association de toute extension avec l'option Any, même si mod_mime ne reconnaît pas l'extension. Ceci peut conduire à des résultats imprévisibles, comme l'envoi de fichiers .old ou .bak contrairement aux souhaits du webmaster.

Par exemple, la configuration suivante va permettre l'inclusion des extensions associées aux gestionnaires et aux filtres dans les vues multiples, tout en excluant les fichiers de type inconnu :

MultiviewsMatch Handlers Filters

L'utilisation de la directive MultiviewsMatch dans une section <Location> ou <LocationMatch> n'est pas permise.

Voir aussi

  • Options
  • mod_negotiation

Directive RemoveCharset

Description: | Supprime toute association de jeu de caractères pour un ensemble d'extensions de noms de fichiers
Syntaxe: | RemoveCharset extension [extension] ...
Contexte: | serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive RemoveCharset permet de supprimer toute association de jeu de caractères pour les fichiers dont les noms possèdent les extensions spécifiées. Ceci permet, au sein des fichiers .htaccess, d'annuler toute association héritée du répertoire parent ou de la configuration du serveur pour un répertoire particulier.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial.

Exemple

RemoveCharset .html .shtml

Directive RemoveEncoding

Description: | Supprime toute association de codage de contenu pour un ensemble d'extensions de noms de fichiers
Syntaxe: | RemoveEncoding extension [extension] ...
Contexte: | serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive RemoveEncoding permet de supprimer toute association de codage pour les fichiers dont les noms possèdent les extensions spécifiées. Ceci permet, au sein des fichiers .htaccess, d'annuler toute association héritée du répertoire parent ou de la configuration du serveur pour un répertoire particulier. Voici un exemple d'utilisation de cette directive :

/foo/.htaccess:

AddEncoding x-gzip .gz
AddType text/plain .asc
<Files "*.gz.asc">
    RemoveEncoding .gz
</Files>

Avec cette configuration, le fichier foo.gz sera marqué comme codé avec gzip, mais foo.gz.asc sera marqué comme fichier texte non codé.

Note

Les directives RemoveEncoding étant traitées après toute directive AddEncoding, il est possible qu'elles annulent les effets de ces dernières si les deux apparaissent dans la configuration du même répertoire.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial.

Directive RemoveHandler

Description: | Supprime toute association de gestionnaire à un ensemble d'extensions de noms de fichiers
Syntaxe: | RemoveHandler extension [extension] ...
Contexte: | serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive RemoveHandler permet de supprimer toute association de gestionnaire à des fichiers dont le nom possède l'extension donnée. Ceci permet, au sein des fichiers .htaccess, d'annuler toute association héritée du répertoire parent ou de la configuration du serveur pour un répertoire particulier. Voici un exemple d'utilisation de cette directive :

/foo/.htaccess:

AddHandler server-parsed .html

/foo/bar/.htaccess:

RemoveHandler .html

Avec cette dernière ligne, les fichiers .html du répertoire /foo/bar seront traités en tant que fichiers normaux, au lieu d'être traités en tant que candidats à l'interprétation (voir le module mod_include module).

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial.

Directive RemoveInputFilter

Description: | Supprime toute association de filtre en entrée à un ensemble d'extensions de noms de fichiers
Syntaxe: | RemoveInputFilter extension [extension] ...
Contexte: | serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive RemoveInputFilter permet de supprimer toute association de filtre en entrée à des fichiers dont le nom possède l'extension donnée. Ceci permet, au sein des fichiers .htaccess, d'annuler toute association héritée du répertoire parent ou de la configuration du serveur pour un répertoire particulier.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial.

Voir aussi

  • AddInputFilter
  • SetInputFilter

Directive RemoveLanguage

Description: | Supprime toute association de langue à un ensemble d'extensions de noms de fichiers
Syntaxe: | RemoveLanguage extension [extension] ...
Contexte: | serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive RemoveLanguage permet de supprimer toute association de langue à des fichiers dont le nom possède l'extension donnée. Ceci permet, au sein des fichiers .htaccess, d'annuler toute association héritée du répertoire parent ou de la configuration du serveur pour un répertoire particulier.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial.

Directive RemoveOutputFilter

Description: | Supprime toute association de filtre en sortie à un ensemble d'extensions de noms de fichiers
Syntaxe: | RemoveOutputFilter extension [extension] ...
Contexte: | serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive RemoveOutputFilter permet de supprimer toute association de filtre en sortie à des fichiers dont le nom possède l'extension donnée. Ceci permet, au sein des fichiers .htaccess, d'annuler toute association héritée du répertoire parent ou de la configuration du serveur pour un répertoire particulier.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial.

Exemple

RemoveOutputFilter shtml

Voir aussi

  • AddOutputFilter

Directive RemoveType

Description: | Supprime toute association de type de contenu à un ensemble d'extensions de noms de fichiers
Syntaxe: | RemoveType extension [extension] ...
Contexte: | serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_mime

La directive RemoveType permet de supprimer toute association de type de médium à des fichiers dont le nom possède l'extension donnée. Ceci permet, au sein des fichiers .htaccess, d'annuler toute association héritée du répertoire parent ou de la configuration du serveur pour un répertoire particulier. Voici un exemple d'utilisation de cette directive :

/foo/.htaccess:

RemoveType .cgi

Cette ligne aura pour effet de supprimer tout traitement spécifique des fichiers .cgi dans le répertoire /foo/ et ses sous-répertoires, et les réponses contenant ce type de fichier ne possèderont pas de champ d'en-tête HTTP Content-Type.

Note

Les directives RemoveType sont traitées après toutes les directives AddType, et il est possible que les effets de ces dernières soient annulés si les deux types de directives sont présents au sein de la configuration du même répertoire.

L'argument extension est insensible à la casse et peut être spécifié avec ou sans le point initial.

Directive TypesConfig

Description: | Le chemin du fichier mime.types
Syntaxe: | TypesConfig chemin-fichier
Défaut: | TypesConfig conf/mime.types
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_mime

La directive TypesConfig permet de définir le chemin du fichier de configuration des types de média. L'argument chemin-fichier est un chemin relatif au répertoire défini par la directive ServerRoot. Ce fichier contient la liste des associations par défaut des extensions de noms de fichiers aux types de contenus. La plupart des administrateurs utilisent le fichier mime.types fourni par leur système d'exploitation, qui associe les extensions de noms de fichiers courantes à la liste officielle des types de média enregistrés par l'IANA et maintenue à http://www.iana.org/assignments/media-types/index.html, ainsi qu'un grand nombre de types non officiels. Ce fichier permet de simplifier le fichier httpd.conf en fournissant la majorité des définitions de types de média, et ses définitions peuvent être écrasées par des directives AddType, selon les besoins. Il est déconseillé de modifier le contenu du fichier mime.types car il peut être remplacé lors d'une mise à jour du serveur.

Le fichier contient des lignes dont le format est identique à celui des arguments d'une directive AddType :

type-médium [extension] ...

Les extensions sont insensibles à la casse. Les lignes vides et les lignes commençant par un dièse (#) sont ignorées. Les lignes vides servent à compléter le fichier mime.types. Apache httpd peut encore déterminer ces types via le module mod_mime_magic.

Merci de ne pas soumettre de requêtes au Projet de Serveur HTTP Apache pour ajouter une entrée dans le fichier mime.types fourni, sauf si : 1) le type de médium est déjà enregistré à l'IANA 2) et si l'extension est largement acceptée et ne provoque pas de conflits d'extensions entre les différentes plate-formes. Les requêtes du type catégorie/x-sous-type seront systématiquement rejetées, ainsi que toute nouvelle extension de deux lettres, car elle ont de fortes chances d'entrer en conflit par la suite avec les inombrables langues préexistantes et les espaces de nommage des jeux de caractères.

Voir aussi

  • mod_mime_magic


mod_mime_magic - Serveur Apache HTTP Version 2.4

Module Apache mod_mime_magic

Description: | Détermine le type MIME d'un fichier à partir de quelques octets de son contenu
Statut: | Extension
Identificateur de Module: | mime_magic_module
Fichier Source: | mod_mime_magic.c

Sommaire

Ce module permet de déterminer le type MIME des fichiers de la même manière que la commande Unix file(1), à savoir en se basant sur les premiers octets du fichier. Il est conçu comme une "seconde ligne de défense" pour les cas où mod_mime ne parvient pas à déterminer le type du fichier.

Ce module est dérivé d'une version libre de la commande Unix file(1) qui utilise des "nombres magiques" et autres marques distinctives issus du contenu du fichier pour essayer de déterminer le type de contenu. Ce module n'est activé que si le fichier magique est spécifié par la directive MimeMagicFile.

Format du fichier magique

Le fichier contient du texte ASCII sur 4 à 5 colonnes. Les lignes vides sont autorisées mais ignorées. Toute ligne commençant par un dièse (#) est un commentaire. Les autres lignes sont interprétées en colonnes comme suit :

Colonne | Description
1 numéro de l'octet à partir duquel la vérification débute
">" indique une dépendance par rapport à la dernière ligne non-">"
2

type de donnée à rechercher

byte | caractère unique
short | entier sur 16 bits selon l'ordre de la machine
long | entier sur 32 bits selon l'ordre de la machine
string | chaîne de taille choisie
date | date au format entier long (secondes depuis le temps Unix epoch/1970)
beshort | entier 16 bits big-endian
belong | entier 32 bits big-endian
bedate | date au format entier 32 bits big-endian
leshort | entier 16 bits little-endian
lelong | entier 32 bits little-endian
ledate | date au format entier 32 bits little-endian
3 | contenu des données à rechercher
4 | type MIME si correspondance
5 | codage MIME si correspondance (optionnel)

Par exemple, les lignes du fichier magique suivantes permettraient de reconnaître certains formats audio :

# Sun/NeXT audio data
0      string      .snd
>12    belong      1       audio/basic
>12    belong      2       audio/basic
>12    belong      3       audio/basic
>12    belong      4       audio/basic
>12    belong      5       audio/basic
>12    belong      6       audio/basic
>12    belong      7       audio/basic
>12    belong     23       audio/x-adpcm

Et celles-ci permettraient de reconnaître la différence entre les fichiers *.doc qui contiennent des documents Microsoft Word et les documents FrameMaker (ce sont des formats de fichiers incompatibles qui possèdent le même suffixe).

# Frame
0  string  \<MakerFile        application/x-frame
0  string  \<MIFFile          application/x-frame
0  string  \<MakerDictionary  application/x-frame
0  string  \<MakerScreenFon   application/x-frame
0  string  \<MML              application/x-frame
0  string  \<Book             application/x-frame
0  string  \<Maker            application/x-frame

# MS-Word
0  string  \376\067\0\043            application/msword
0  string  \320\317\021\340\241\261  application/msword
0  string  \333\245-\0\0\0           application/msword

Un champ optionnel codage MIME peut être ajouté dans la cinquième colonne. Par exemple, cette ligne permet de reconnaître les fichiers compressés par gzip et définissent le type de codage.

# gzip (GNU zip, à ne pas confondre avec
#       l'archiveur zip [Info-ZIP/PKWARE])

0  string  \037\213  application/octet-stream  x-gzip

Problèmes liés aux performances

Ce module n'est pas fait pour tous les systèmes. Si votre système parvient à peine à supporter sa charge, ou si vous testez les performances d'un serveur web, il est déconseillé d'utiliser ce module car son fonctionnement a un prix en matière de ressources consommées.

Des efforts ont cependant été fournis pour améliorer les performances du code original de la commande file(1) en l'adaptant pour fonctionner sur un serveur web à forte charge. Il a été conçu pour un serveur sur lequel des milliers d'utilisateurs publient leurs propres documents, ce qui est probablement très courant sur un intranet. Il s'avère souvent bénéfique qu'un serveur puisse prendre des décisions plus pertinentes à propos du contenu d'un fichier que celles se basant sur le nom du fichier seul, ne serait-ce que pour diminuer le nombre d'appels du type "pourquoi ma page ne s'affiche-t-elle pas ?" survenant lorsque les utilisateurs nomment leurs fichiers incorrectement. Vous devez déterminer si la charge supplémentaire convient à votre environnement.

Notes

Les notes suivantes s'appliquent au module mod_mime_magic et sont incluses ici pour conformité avec les restrictions de copyright des contributeurs qui requièrent de les accepter.

Note de traduction : ces informations de type légal ne sont pas traductibles

mod_mime_magic: MIME type lookup via file magic numbers
Copyright (c) 1996-1997 Cisco Systems, Inc.

This software was submitted by Cisco Systems to the Apache Group in July 1997. Future revisions and derivatives of this source code must acknowledge Cisco Systems as the original contributor of this module. All other licensing and usage conditions are those of the Apache Group.

Some of this code is derived from the free version of the file command originally posted to comp.sources.unix. Copyright info for that program is included below as required.

- Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin.

This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California.

Permission is granted to anyone to use this software for any purpose on any computer system, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from flaws in it.
  2. The origin of this software must not be misrepresented, either by explicit claim or by omission. Since few users ever read sources, credits must appear in the documentation.
  3. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software. Since few users ever read sources, credits must appear in the documentation.
  4. This notice may not be removed or altered.

For compliance with Mr Darwin's terms: this has been very significantly modified from the free "file" command.

  • all-in-one file for compilation convenience when moving from one version of Apache to the next.
  • Memory allocation is done through the Apache API's pool structure.
  • All functions have had necessary Apache API request or server structures passed to them where necessary to call other Apache API routines. (i.e., usually for logging, files, or memory allocation in itself or a called function.)
  • struct magic has been converted from an array to a single-ended linked list because it only grows one record at a time, it's only accessed sequentially, and the Apache API has no equivalent of realloc().
  • Functions have been changed to get their parameters from the server configuration instead of globals. (It should be reentrant now but has not been tested in a threaded environment.)
  • Places where it used to print results to stdout now saves them in a list where they're used to set the MIME type in the Apache request record.
  • Command-line flags have been removed since they will never be used here.

Directive MimeMagicFile

Description: | Active la détermination du type MIME en se basant sur le contenu du fichier et en utilisant le fichier magique spécifié
Syntaxe: | MimeMagicFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_mime_magic

La directive MimeMagicFile permet d'activer ce module, le fichier par défaut fourni étant conf/magic. Les chemins sans slash '/' de début sont relatifs au répertoire défini par la directive ServerRoot. Les serveurs virtuels utilisent le même fichier que le serveur principal sauf si un fichier spécifique a été défini pour ce serveur virtuel, auquel cas c'est ce dernier fichier qui sera utilisé.

Exemple

MimeMagicFile conf/magic


mod_negotiation - Serveur Apache HTTP Version 2.4

Module Apache mod_negotiation

Description: | Effectue la négociation de contenu
Statut: | Base
Identificateur de Module: | negotiation_module
Fichier Source: | mod_negotiation.c

Sommaire

La négociation de contenu, ou plus précisément la sélection de contenu, est la sélection parmi plusieurs documents disponibles, du document qui "colle" au plus près des possibilités du client. Pour y parvenir, deux méthodes sont employées.

  • Une table de correspondances de types (un fichier associé au gestionnaire type-map) qui contient une liste explicite des fichiers contenant les différentes variantes.
  • Une recherche multivues (Multiviews) (activée par l'Options Multiviews), où le serveur effectue une recherche de correspondance de modèle de nom de fichier implicite, et fait son choix parmi les résultats.

Traitement des bugs

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

Voir aussi

  • Options
  • mod_mime
  • Négociation de contenu
  • Variables d'environnement

Tables de correspondances de types

Une table de correspondances de types possède un format similaire à celui des en-têtes de messagerie RFC822. Elle contient des descriptions de documents séparées par des lignes vides, toute ligne commençant par un dièse ('#') étant considérée comme un commentaire. Une description de document comporte plusieurs enregistrements d'en-têtes ; chaque enregistrement peut être réparti sur plusieurs lignes à condition que les lignes supplémentaires commencent par un ou plusieurs espaces. Lors du traitement, les espaces de début de ligne seront supprimés et les lignes concaténées. L'enregistrement d'un en-tête comprend un mot-clé qui se termine toujours par un caractère "deux-points" ':', suivi d'une valeur. Les espaces sont autorisés entre le nom d'en-tête et sa valeur, ainsi qu'entre les différents éléments de la valeur. Les en-têtes autorisés sont :

Content-Encoding:
Le codage du fichier. Apache ne reconnaît que les codages définis par une directive AddEncoding. Sont normalement inclus les codages x-compress pour les fichiers compressés avec compress, et x-gzip pour les fichiers compressés avec gzip. Le préfixe x- est ignoré lors des comparaisons de codages.
Content-Language:
Le(s) langage(s) de la variante, sous la forme d'un symbole de langage Internet standard (RFC 1766). Par exemple, en correspond à l'anglais. Si la variante contient plusieurs langages, ils sont séparés par des virgules.
Content-Length:
La taille du fichier en octets. Si cet en-tête n'est pas présent, c'est la taille réelle du fichier qui est utilisée.
Content-Type:
Le type MIME du document avec des paramètres optionnels. Les paramètres sont séparés du type de médium ainsi qu'entre eux par un point-virgule, et possèdent la syntaxe nom=valeur. Les paramètres courants sont :
level
un entier spécifiant la version du type de média. Pour text/html, la valeur par défaut est 2, sinon 0.
qs
un nombre en virgule flottante de 0[.000] à 1[.000], indiquant la "qualité" relative de la variante courante par rapport aux autres variantes disponibles, indépendamment des possibilités du client. Par exemple, un fichier jpeg est en général une source de qualité supérieure à un fichier ascii s'il est censé représenter une image. Cependant, si la ressource représentée est une image ascii, un fichier ascii possèdera une qualité supérieure à un fichier jpeg. Toutes les valeurs de qs sont donc spécifiques à une certaine ressource.

Exemple

Content-Type: image/jpeg; qs=0.8

URI:
l'URI du fichier contenant la variante (du type de médium donné, codé selon le codage de contenu donné). Cet URI est considéré comme relatif au fichier de correspondances ; il doit être situé sur le même serveur, et doit faire référence au fichier auquel le client se verrait accorder l'accès s'il était requis directement.
Body:
Le contenu réel de la ressource peut être inclus dans la table de correspondances en utilisant l'en-tête Body. Cet en-tête doit contenir une chaîne désignant un délimiteur pour le contenu du corps. Les lignes suivantes du fichier de correspondances de types seront alors considérées comme parties du corps de la ressource jusqu'à ce que le délimiteur soit détecté.

Exemple:

Body:----xyz----
<html>
<body>
<p>Contenu de la page.</p>
</body>
</html>
----xyz----

Considérons une ressource, document.html, disponible en anglais, en français et en allemand. Les fichiers correspondants se nomment respectivement document.html.en, document.html.fr, et document.html.de. Le fichier de correspondances de types se nommera document.html.var et contiendra ce qui suit :

URI: document.html

Content-language: en
Content-type: text/html
URI: document.html.en

Content-language: fr
Content-type: text/html
URI: document.html.fr

Content-language: de
Content-type: text/html
URI: document.html.de

Ces quatre fichiers doivent se trouver dans le même répertoire, et le fichier .var doit être associé au gestionnaire type-map via une directive AddHandler :

AddHandler type-map .var

A l'arrivée d'une requête pour la ressource document.html.var, la variante de document.html qui correspond le mieux à la préference de langage spécifiée dans l'en-tête de la requête de l'utilisateur Accept-Language sera choisie.

Si Multiviews est activée, et si MultiviewsMatch est définie à "handlers" ou "any", une requête pour document.html va rechercher document.html.var, et continuer la négociation avec le gestionnaire explicite type-map.

D'autres directives de configuration, comme Alias, peuvent être utilisées pour associer document.html avec document.html.var.

Multivues

Une recherche Multivues est activée par l'Options Multiviews. Si le serveur reçoit une requête pour /un/répertoire/foo, et si /un/répertoire/foo n'existe pas, le serveur parcourt le répertoire à la recherche de tous les fichiers de nom foo.*, et simule véritablement une correspondance de type qui nomme tous ces fichiers en leur assignant les mêmes type de média et codage de contenu qu'ils auraient eus si le client avait requis l'un d'entre eux avec son nom complet. Il choisit ensuite le fichier qui correspond le mieux au profile du client, puis renvoie le document.

La directive MultiviewsMatch définit si Apache doit prendre en compte les fichiers qui ne comportent pas de métadonnées de négociation de contenu lors du choix du fichier à servir.

Directive CacheNegotiatedDocs

Description: | Permet la mise en cache au niveau des serveurs mandataires des documents dont le contenu a été négocié
Syntaxe: | CacheNegotiatedDocs On|Off
Défaut: | CacheNegotiatedDocs Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_negotiation

Si elle est définie à "on", cette directive permet la mise en cache au niveau des serveurs mandataires des documents dont le contenu a été négocié. Le processus de mise en cache sera alors plus efficace, mais des clients se trouvant derrière le mandataire seront alors susceptibles de se voir servir des versions de documents qui ne correspondent pas forcément à leurs attentes.

Cette directive ne s'applique qu'aux requêtes en provenance de navigateurs HTTP/1.0. HTTP/1.1 fournit un bien meilleur contrôle de la mise en cache des documents au contenu négocié, et cette directive n'a aucun effet sur les réponses aux requêtes HTTP/1.1.

Directive ForceLanguagePriority

Description: | Action à entreprendre si un document acceptable unique n'est pas trouvé
Syntaxe: | ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]
Défaut: | ForceLanguagePriority Prefer
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_negotiation

La directive ForceLanguagePriority utilise le langage défini par la directive LanguagePriority pour terminer la négociation lorsque le serveur n'est pas en mesure de trouver une solution satisfaisante unique.

ForceLanguagePriority Prefer utilise la directive LanguagePriority pour servir le résultat d'un choix unique, au lieu de renvoyer un résultat HTTP 300 (MULTIPLE CHOICES), lorsque que plusieurs choix équivalents sont disponibles. Par exemple, avec les deux directives ci-dessous, si l'en-tête Accept-Language de l'utilisateur assigne à en et de une qualité de .500 (les deux langages sont également acceptables), alors c'est la première variante acceptable de langue en qui sera servie.

LanguagePriority en fr de
ForceLanguagePriority Prefer

ForceLanguagePriority Fallback utilise la directive LanguagePriority pour servir un résultat valide, au lieu de renvoyer un résultat HTTP 406 (NOT ACCEPTABLE). Avec les deux directives ci-dessous, si l'en-tête Accept-Language de l'utilisateur ne mentionne que les réponses de langage es, et si aucune variante dans cette langue n'est trouvée, c'est la première variante de la liste définie par la directive LanguagePriority qui sera servie.

LanguagePriority en fr de
ForceLanguagePriority Fallback

Les deux options, Prefer et Fallback, peuvent être spécifiées, de façon à ce que la variante servie soit la première variante qui convient définie par la directive LanguagePriority si plusieurs variantes sont également acceptables, ou le premier document disponible si aucune variante ne convient à la liste de langages acceptables fournie par le client.

Voir aussi

  • AddLanguage

Directive LanguagePriority

Description: | L'ordre de priorité des variantes de langages pour les cas où le client n'a pas formulé de préférences
Syntaxe: | LanguagePriority langage-MIME [langage-MIME] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_negotiation

La directive LanguagePriority permet de définir, au cours du traitement d'une requête Multivues, l'ordre de priorité des variantes de langages pour les cas où le client n'a pas formulé de préférences. La liste énumère les langages-MIME dans un ordre de préférences décroissantes.

LanguagePriority en fr de

Dans le cas d'une requête pour foo.html, si foo.html.fr et foo.html.de existent, et si le client n'a pas formulé de préférences, c'est le fichier foo.html.fr qui sera renvoyé.

Notez que cette directive n'a d'effet que si le 'meilleur' langage n'a pas pu être déterminé d'une autre manière ou si la valeur de la directive ForceLanguagePriority est différente de None. En général, c'est le client qui détermine le langage préféré, non le serveur.

Voir aussi

  • AddLanguage


mod_nw_ssl - Serveur Apache HTTP Version 2.4

Module Apache mod_nw_ssl

Description: | Active le chiffrement SSL pour Netware
Statut: | Base
Identificateur de Module: | nwssl_module
Fichier Source: | mod_nw_ssl.c
Compatibilité: | NetWare seulement

Sommaire

Ce module active le chiffrement SSL sur un port spécifique. Il s'appuie sur la fonctionnalité de chiffrement SSL intégrée au système d'exploitation Netware.

Directive NWSSLTrustedCerts

Description: | Liste de certificats clients supplémentaires
Syntaxe: | NWSSLTrustedCerts nom-fichier [nom-fichier] ...
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_nw_ssl

Cette directive permet de spécifier une liste de fichiers (au format DER) contenant des certificats clients utilisés lors de l'établissement d'une connexion SSL mandatée. Chaque certificat client utilisé par un serveur doit être enregistré séparément dans son propre fichier .der.

Directive NWSSLUpgradeable

Description: | Permet de promouvoir une connexion non SSL au statut de connexion SSL à la demande
Syntaxe: | NWSSLUpgradeable [adresse-IP:]num-port
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_nw_ssl

Cette directive permet de promouvoir une connexion établie sur l'adresse IP et/ou le port spécifiés au statut de connexion SSL à la demande du client. L'adresse et/ou le port doivent avoir été définis au préalable par une directive Listen.

Directive SecureListen

Description: | Active le chiffrement SSL pour le port spécifié
Syntaxe: | SecureListen [adresse-IP:]num-port nom-certificat [MUTUAL]
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_nw_ssl

Cette directive permet de spécifier le port et le nom de certificat de style eDirectory qui seront utilisés pour activer le chiffrement SSL. En outre, un troisième paramètre optionnel permet d'activer l'authentification mutuelle.


mod_privileges - Serveur Apache HTTP Version 2.4

Module Apache mod_privileges

Description: | Support des privilèges de Solaris et de l'exécution des serveurs virtuels sous différents identifiants utilisateurs.
Statut: | Expérimental
Identificateur de Module: | privileges_module
Fichier Source: | mod_privileges.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache sur les plates-formes Solaris 10 et OpenSolaris

Sommaire

Ce module permet l'exécution de différents serveurs virtuels sous différents identifiants Unix User et Group, et avec différents Privilèges Solaris. En particulier, il apporte au problème de séparation des privilèges entre les différents serveurs virtuels la solution que devait apporter le module MPM abandonné perchild. Il apporte aussi d'autres améliorations en matière de sécurité.

À la différence de perchild, mod_privileges n'est pas un module MPM. Il travaille au sein d'un modèle de traitement pour définir les privilèges et les User/Group pour chaque requête dans un même processus. Il n'est donc pas compatible avec les MPM threadés, et refusera de s'exécuter en cas d'utilisation d'un de ces derniers.

mod_privileges traite des problèmes de sécurité similaires à ceux de suexec ; mais à la différence de ce dernier, il ne s'applique pas seulement aux programmes CGI, mais à l'ensemble du cycle de traitement d'une requête, y compris les applications in-process et les sous-processus. Il convient particulièrement à l'exécution des applications PHP sous mod_php, qui est lui-même incompatible avec les modules MPM threadés. Il est également bien adapté aux autres applications de type script in-process comme mod_perl, mod_python, et mod_ruby, ainsi qu'aux applications en langage C telles que les modules Apache pour lesquels la séparation des privilèges constitue un problème.

Considérations à propos de sécurité

mod_privileges introduit de nouveaux problèmes de sécurité dans les situations où du code non sûr peut s'exécuter à l'intérieur du processus du serveur web. Ceci s'applique aux modules non sûrs, et aux scripts s'exécutant sous des modules comme mod_php ou mod_perl. Les scripts s'exécutant en externe (comme par exemple les scripts CGI ou ceux s'exécutant sur un serveur d'applications derrière mod_proxy ou mod_jk) ne sont pas concernés.

Les principaux problèmes de sécurité que l'on rencontre avec mod_privileges sont :

  • L'exécution sous un utilisateur système pose les mêmes problèmes de sécurité que mod_suexec, et pratiquement les mêmes que cgiwrap et suphp.
  • Une extension utilisateur (module ou script) malveillante, écrite en connaissant les mécanismes utilisés par mod_privileges, pourrait élever ses privilèges à tout niveau accessible au processus httpd dans tout serveur virtuel. Ceci introduit de nouveaux risques si (et seulement si) mod_privileges est compilé avec l'option BIG_SECURITY_HOLE.
  • Une extension utilisateur (module ou script) malveillante, écrite en connaissant les mécanismes utilisés par mod_privileges, pourrait élever ses privilèges pour s'attribuer l'identifiant utilisateur d'un autre utilisateur (et/ou groupe) système.

La directive PrivilegesMode vous permet de sélectionner soit le mode FAST, soit le mode SECURE. Vous pouvez panacher les modes en utilisant par exemple le mode FAST pour les utilisateurs de confiance et les chemins contenant du code entièrement audité, tout en imposant le mode SECURE où un utilisateur non sûr a la possibilité d'introduire du code.

Avant de décrire les modes, il nous faut présenter les cas d'utilisation de la cible : "Benign" ou "Hostile". Dans une situation "Benign", vous voulez séparer les utilisateurs pour leur confort, et les protéger, ainsi que le serveur, contre les risques induits par les erreurs involontaires. Dans une situation "Hostile" - par exemple l'hébergement d'un site commercial - il se peut que des utilisateurs attaquent délibérément le serveur ou s'attaquent entre eux.

Mode FAST
En mode FAST, les requêtes sont traitées "in-process" avec les uid/gid et privilèges sélectionnés, si bien que la surcharge est négligeable. Ceci convient aux situations "Benign", mais n'est pas sécurisé contre un attaquant augmentant ses privilèges avec un module ou script "in-process".
Mode SECURE
Une requête en mode SECURE génère un sous-processus qui supprime les privilèges. Ce comportement est très similaire à l'exécution d'un programme CGI avec suexec, mais il reste valable tout au long du cycle de traitement de la requête, avec en plus l'avantage d'un contrôle précis des privilèges.

Vous pouvez sélectionner différents PrivilegesModes pour chaque serveur virtuel, et même dans un contexte de répertoire à l'intérieur d'un serveur virtuel. Le mode FAST convient lorsque les utilisateurs sont sûrs et/ou n'ont pas le privilège de charger du code "in-process". Le mode SECURE convient dans les cas où du code non sûr peut s'exécuter "in-process". Cependant, même en mode SECURE, il n'y a pas de protection contre un utilisateur malveillant qui a la possibilité d'introduire du code supportant les privilèges avant le début du cycle de traitement de la requête.

Directive DTracePrivileges

Description: | Détermine si les privilèges requis par dtrace sont activés.
Syntaxe: | DTracePrivileges On|Off
Défaut: | DTracePrivileges Off
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | >Disponible sous Solaris 10 et OpenSolaris avec les modules MPM non-threadés (prefork ou MPM personnalisé).

Cette directive qui s'applique à l'ensemble du serveur permet de déterminer si Apache s'exécutera avec les privilèges requis pour exécuter dtrace. Notez que la définition DTracePrivileges On n'activera pas à elle-seule DTrace, mais que DTracePrivileges Off l'empêchera de fonctionner.

Directive PrivilegesMode

Description: | Fait un compromis entre d'une part l'efficacité et la vitesse de traitement et d'autre part la sécurité à l'encontre des codes malicieux supportant les privilèges.
Syntaxe: | PrivilegesMode FAST|SECURE|SELECTIVE
Défaut: | PrivilegesMode FAST
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | Disponible sous Solaris 10 et OpenSolaris avec des modules MPMs non threadés (comme prefork ou un module personnalisé).

Cette directive permet de faire un compromis entre les performances et la sécurité à l'encontre des codes malicieux supportant les privilèges. En mode SECURE, chaque requête est traitée dans un sous-processus sécurisé, ce qui induit une dégradation sensible des performances. En mode FAST, le serveur n'est pas protégé contre l'augmentation de privilège comme décrit plus haut.

Cette directive est sensiblement différente selon qu'elle se trouve dans une section <Directory> (ou Location/Files/If) ou au niveau global ou dans un <VirtualHost>.

Au niveau global, elle définit un comportement par défaut dont hériteront les serveurs virtuels. Dans un serveur virtuel, les modes FAST ou SECURE agissent sur l'ensemble de la requête HTTP, et toute définition de ces modes dans une section <Directory> sera ignorée. Le pseudo-mode SELECTIVE confie le choix du mode FAST ou SECURE aux directives contenues dans une section<Directory>.

Dans une section <Directory>, elle ne s'applique que lorsque le mode SELECTIVE a été défini pour le serveur virtuel. Seuls FAST ou SECURE peuvent être définis dans ce contexte (SELECTIVE n'aurait pas de sens).

Avertissement

Lorsque le mode SELECTIVE a été défini pour un serveur virtuel, l'activation des privilèges doit être reportée après la détermination, par la phase de comparaison du traitement de la requête, du contexte <Directory> qui s'applique à la requête. Ceci peut donner à un attaquant l'opportunité d'introduire du code via une directive RewriteMap s'exécutant au niveau global ou d'un serveur virtuel avant que les privilèges n'aient été supprimés et l'uid/gid défini.

Directive VHostCGIMode

Description: | Détermine si le serveur virtuel peut exécuter des sous-processus, et définit les privilèges disponibles pour ces dernier.
Syntaxe: | VHostCGIMode On|Off|Secure
Défaut: | VHostCGIMode On
Contexte: | serveur virtuel
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | Disponible sous Solaris 10 et OpenSolaris avec les modules MPM non-threadés (prefork ou MPM personnalisé).

Détermine si le serveur virtuel est autorisé à exécuter fork et exec, et définit les privilèges requis pour exécuter des sous-processus. Si cette directive est définie à Off le serveur virtuel ne disposera d'aucun privilège et ne pourra exécuter ni des programmes ou scripts CGI classiques via le module traditionnel mod_cgi, ni des programmes externes similaires tels que ceux créés via le module mod_ext_filter ou les programmes de réécriture externes utilisés par la directive RewriteMap. Notez que ceci n'empêche pas l'exécution de programmes CGI via d'autres processus et sous d'autres modèles de sécurité comme mod_fcgid, ce qui est la solution recommandée sous Solaris.

Si cette directive est définie à On ou Secure, le serveur virtuel pourra exécuter les scripts et programmes externes cités ci-dessus. Définir la directive VHostCGIMode à Secure a pour effet supplémentaire de n'accorder aucun privilège aux sous-processus, comme décrit dans la directive VHostSecure.

Directive VHostCGIPrivs

Description: | Assigne des privilèges au choix aux sous-processus créés par un serveur virtuel.
Syntaxe: | VHostPrivs [+-]?nom-privilège [[+-]?nom-privilège] ...
Défaut: | Aucun
Contexte: | serveur virtuel
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | Disponible sous Solaris 10 et OpenSolaris avec les modules MPM non-threadés (prefork ou MPM personnalisé) et lorsque mod_privileges est construit avec l'option de compilation BIG_SECURITY_HOLE.

La directive VHostCGIPrivs permet d'assigner des privilèges au choix aux sous-processus créés par un serveur virtuel, comme décrit dans la directive VHostCGIMode. Chaque nom-privilège correspond à un privilège Solaris tel que file_setid ou sys_nfs.

nom-privilège peut être éventuellement préfixé par + ou -, ce qui va respectivement accorder ou refuser le privilège. Si nom-privilège est spécifié sans + ni -, tous les autres privilèges préalablement assignés au serveur virtuel seront refusés. Cette directive permet de construire aisément votre propre jeu de privilèges en annulant tout réglage par défaut.

Sécurité

L'utilisation de cette directive peut ouvrir d'immenses trous de sécurité dans les sous-processus Apache, jusqu'à leur exécution avec les droits de root. Ne l'utilisez que si vous êtes absolument sûr de comprendre ce que vous faites !

Directive VHostGroup

Description: | Définit l'identifiant du groupe sous lequel s'exécute un serveur virtuel.
Syntaxe: | VHostGroup identifiant-groupe-unix
Défaut: | Hérite de l'identifiant du groupe spécifié par la directive Group
Contexte: | serveur virtuel
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | Disponible sous Solaris 10 et OpenSolaris avec les modules MPM non-threadés (prefork ou MPM personnalisé).

La directive VHostGroup permet de définir l'identifiant du groupe unix sous lequel le serveur va traiter les requêtes par l'intermédiaire d'un serveur virtuel. L'identifiant du groupe est défini avant le traitement de la requête, puis restauré à sa valeur de départ via les Privilèges Solaris. Comme la définition s'applique au processus, cette directive est incompatible avec les modules MPM threadés.

Unix-group peut être :

Un nom de groupe
Fait référence au groupe donné par son nom.
# suivi d'un numéro de groupe.
Fait référence au groupe donné par son numéro.

Sécurité

Cette directive ne peut pas être utilisée pour exécuter Apache en tant que root ! Elle est tout de même susceptible de poser des problèmes de sécurité similaires à ceux décrits dans la documentation de suexec.

Voir aussi

  • Group
  • SuexecUserGroup

Directive VHostPrivs

Description: | Assigne des privilèges à un serveur virtuel.
Syntaxe: | VHostPrivs [+-]?nom-privilège [[+-]?nom-privilège] ...
Défaut: | Aucun
Contexte: | serveur virtuel
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | Disponible sous Solaris 10 et OpenSolaris avec les modules MPM non-threadés (prefork ou MPM personnalisé) et lorsque mod_privileges est construit avec l'option de compilation BIG_SECURITY_HOLE.

La directive VHostPrivs permet d'assigner des privilèges au choix à un serveur virtuel. Chaque nom-privilège correspond à un privilège Solaris tel que file_setid ou sys_nfs.

nom-privilège peut être éventuellement préfixé par + ou -, ce qui va respectivement accorder ou refuser le privilège. Si nom-privilège est spécifié sans + ni -, tous les autres privilèges préalablement assignés au serveur virtuel seront refusés. Cette directive permet de construire aisément votre propre jeu de privilèges en annulant tout réglage par défaut.

Sécurité

L'utilisation de cette directive peut ouvrir d'immenses trous de sécurité dans Apache, jusqu'au traitement de requêtes avec les droits de root. Ne l'utilisez que si vous êtes absolument sûr de comprendre ce que vous faites !

Directive VHostSecure

Description: | Détermine si le serveur s'exécute avec une sécurité avancée pour les serveurs virtuels.
Syntaxe: | VHostSecure On|Off
Défaut: | VHostSecure On
Contexte: | serveur virtuel
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | Disponible sous Solaris 10 et OpenSolaris avec les modules MPM non-threadés (prefork ou MPM personnalisé).

Détermine si les serveurs virtuels traitent les requêtes avec une sécurité avancée en supprimant les Privilèges rarement requis par un serveur web, mais disponibles par défaut pour un utilisateur Unix standard, et donc susceptibles d'être demandés par des modules et des applications. Il est recommandé de conserver la définition par défaut (On), sauf si elle empêche une application de fonctionner. Comme la définition s'applique au processus, cette directive est incompatible avec les modules MPM threadés.

Note

Le fait que la directive VHostSecure empêche une application de fonctionner peut constituer un signal d'avertissement indiquant que la sécurité de l'application doit être revue.

Directive VHostUser

Description: | Définit l'identifiant utilisateur sous lequel s'exécute un serveur virtuel.
Syntaxe: | VHostUser identifiant-utilisateur-unix
Défaut: | Hérite de l'identifiant utilisateur spécifié par la directive User
Contexte: | serveur virtuel
Statut: | Expérimental
Module: | mod_privileges
Compatibilité: | Disponible sous Solaris 10 et OpenSolaris avec les modules MPM non-threadés (prefork ou MPM personnalisé).

La directive VHostUser permet de définir l'identifiant utilisateur unix sous lequel le serveur va traiter les requêtes par l'intermédiaire d'un serveur virtuel. L'identifiant utilisateur est défini avant le traitement de la requête, puis restauré à sa valeur de départ via les Privilèges Solaris. Comme la définition s'applique au processus, cette directive est incompatible avec les modules MPM threadés.

identifiant-utilisateur-unix peut être :

Un nom d'utilisateur
Fait référence à l'utilisateur donné par son nom.
# suivi d'un numéro d'utilisateur.
Fait référence à l'utilisateur donné par son numéro.

Sécurité

Cette directive ne peut pas être utilisée pour exécuter Apache en tant que root ! Elle est tout de même susceptible de poser des problèmes de sécurité similaires à ceux décrits dans la documentation de suexec.

Voir aussi

  • User
  • SuexecUserGroup


mod_proxy - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy

Description: | Serveur mandataire/passerelle multi-protocole
Statut: | Extension
Identificateur de Module: | proxy_module
Fichier Source: | mod_proxy.c

Sommaire

Avertissement

N'activez pas la fonctionnalité de mandataire avec la directive ProxyRequests avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux pour votre réseau, mais aussi pour l'Internet au sens large.

mod_proxy et ses modules associés implémentent un mandataire/passerelle pour le serveur HTTP Apache, et supportent de nombreux protocoles courants, ainsi que plusieurs algorithmes de répartition de charge. Le support de protocoles et d'algorithmes de répartition de charge supplémentaires peut être assuré par des modules tiers.

Un jeu de modules chargés dans le serveur permet de fournir les fonctionnalités souhaitées. Ces modules peuvent être inclus statiquement à la compilation, ou dynamiquement via la directive LoadModule. Ce jeu de module doit comporter :

  • mod_proxy, qui fournit les fonctionnalités de base d'un mandataire
  • mod_proxy_balancer et un ou plusieurs modules de répartition, si la répartition de charge doit être mise en oeuvre (Voir la documentation de mod_proxy_balancer pour plus de détails).
  • un ou plusieurs modules de types de mandataire, ou protocoles :
    Protocole | Module
    AJP13 (Protocole Apache JServe version 1.3) | mod_proxy_ajp
    CONNECT (pour SSL) | mod_proxy_connect
    FastCGI | mod_proxy_fcgi
    ftp | mod_proxy_ftp
    HTTP/0.9, HTTP/1.0, et HTTP/1.1 | mod_proxy_http
    SCGI | mod_proxy_scgi
    WS and WSS (Web-sockets) | mod_proxy_wstunnel

En outre, d'autres modules fournissent des fonctionnalités étendues. mod_cache et ses modules associés fournissent la mise en cache. Les directives SSLProxy* du module mod_ssl permettent de contacter des serveurs distants en utilisant le protocole SSL/TLS. Ces modules additionnels devront être chargés et configurés pour pouvoir disposer de ces fonctionnalités.

Traitement des bugs

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

Voir aussi

  • mod_cache
  • mod_proxy_ajp
  • mod_proxy_connect
  • mod_proxy_fcgi
  • mod_proxy_ftp
  • mod_proxy_http
  • mod_proxy_scgi
  • mod_proxy_wstunnel
  • mod_proxy_balancer
  • mod_ssl

Mandataires directs et mandataires/passerelles inverses

Le serveur HTTP Apache peut être configuré dans les deux modes mandataire direct et mandataire inverse (aussi nommé mode passerelle).

Un mandataire direct standard est un serveur intermédiaire qui s'intercale entre le client et le serveur demandé. Pour obtenir un contenu hébergé par le serveur demandé, le client envoie une requête au mandataire en nommant le serveur demandé comme cible. Le mandataire extrait alors le contenu depuis le serveur demandé et le renvoie enfin au client. Le client doit être configuré de manière appropriée pour pouvoir utiliser le mandataire direct afin d'accéder à d'autres sites.

L'accès à Internet depuis des clients situés derrière un pare-feu est une utilisation typique du mandataire direct. Le mandataire direct peut aussi utiliser la mise en cache (fournie par mod_cache) pour réduire la charge du réseau.

La fonctionnalité de mandataire direct est activée via la directive ProxyRequests. Comme les mandataires directs permettent aux clients d'accéder à des sites quelconques via votre serveur et de dissimuler leur véritable origine, il est indispensable de sécuriser votre serveur de façon à ce que seuls les clients autorisés puissent accéder à votre serveur avant d'activer la fonctionnalité de mandataire direct.

Un mandataire inverse (ou passerelle), quant à lui, apparaît au client comme un serveur web standard. Aucune configuration particulière du client n'est nécessaire. Le client adresse ses demandes de contenus ordinaires dans l'espace de nommage du mandataire inverse. Ce dernier décide alors où envoyer ces requêtes, et renvoie le contenu au client comme s'il l'hébergeait lui-même.

L'accès d'utilisateurs depuis Internet vers un serveur situé derrière un pare-feu est une utilisation typique du mandataire inverse. On peut aussi utiliser les mandataires inverses pour mettre en oeuvre une répartition de charge entre plusieurs serveurs en arrière-plan, ou fournir un cache pour un serveur d'arrière-plan plus lent. Les mandataires inverses peuvent aussi tout simplement servir à rassembler plusieurs serveurs dans le même espace de nommage d'URLs.

La fonctionnalité de mandataire inverse est activée via la directive ProxyPass ou le drapeau [P] de la directive RewriteRule. Il n'est pas nécessaire de définir ProxyRequests pour configurer un mandataire inverse.

Exemples simples

Les exemples ci-dessous illustrent de manière très basique la mise en oeuvre de la fonctionnalité de mandataire et ne sont là que pour vous aider à démarrer. Reportez-vous à la documentation de chaque directive.

Si en outre, vous désirez activer la mise en cache, consultez la documentation de mod_cache.

Mandataire inverse

ProxyPass "/foo" "http://foo.example.com/bar"
ProxyPassReverse "/foo" "http://foo.example.com/bar"

Mandataire direct

ProxyRequests On
ProxyVia On

<Proxy "*">
  Require host internal.example.com
</Proxy>

Accès via un gestionnaire

Vous pouvez aussi forcer le traitement d'une requête en tant que requête de mandataire inverse en créant un gestionnaire de transfert approprié. Dans l'exemple suivant, toutes les requêtes pour des scripts PHP seront transmises au serveur FastCGI spécifié via un mandat inverse :

Scripts PHP et mandataire inverse

<FilesMatch "\.php$">
    # Les sockets Unix nécessitent une version 2.4.7 ou supérieure du
    # serveur HTTP Apache
    SetHandler  "proxy:unix:/path/to/app.sock|fcgi://localhost/"
</FilesMatch>

Cette fonctionnalité est disponible à partir de la version 2.4.10 du serveur HTTP Apache.

Workers

Le mandataire gère la configuration et les paramètres de communication des serveurs originaux au sein d'objets nommés workers. Deux types de worker sont fournis : le worker par défaut du mandataire direct et le worker par défaut du mandataire inverse. Il est aussi possible de définir explicitement des workers supplémentaires.

Les deux workers par défaut possèdent une configuration figée et seront utilisés si aucun autre worker ne correspond à la requête. Ils ne réutilisent pas les connexions et n'utilisent pas les connexions HTTP persistantes (Keep-Alive). En effet, les connexions TCP vers le serveur original sont fermées et ouvertes pour chaque requête.

Les workers définis explicitement sont identifiés par leur URL. Ils sont en général définis via les directives ProxyPass ou ProxyPassMatch lorsqu'on les utilise dans le cadre d'un mandataire inverse :

ProxyPass "/example" "http://backend.example.com" connectiontimeout=5 timeout=30

Cette directive va créer un worker associé à l'URL du serveur original http://backend.example.com qui utilisera les valeurs de timeout données. Lorsqu'ils sont utilisés dans le cadre d'un mandataire direct, les workers sont en général définis via la directive ProxySet,

ProxySet "http://backend.example.com" connectiontimeout=5 timeout=30

ou encore via les directives Proxy et ProxySet :

<Proxy "http://backend.example.com">
  ProxySet connectiontimeout=5 timeout=30
</Proxy>

L'utilisation de workers définis explicitement dans le mode mandataire direct n'est pas très courante, car les mandataires directs communiquent en général avec de nombreux serveurs originaux. La création explicite de workers pour certains serveurs originaux peut cependant s'avérer utile si ces serveurs sont très souvent sollicités. A leur niveau, les workers explicitement définis ne possèdent aucune notion de mandataire direct ou inverse. Ils encapsulent un concept de communication commun avec les serveurs originaux. Un worker créé via la directive ProxyPass pour être utilisé dans le cadre d'un mandataire inverse sera aussi utilisé dans le cadre d'un mandataire directe chaque fois que l'URL vers le serveur original correspondra à l'URL du worker, et vice versa.

L'URL qui identifie un worker correspond à l'URL de son serveur original, y compris un éventuel chemin donné :

ProxyPass "/examples" "http://backend.example.com/examples"
ProxyPass "/docs" "http://backend.example.com/docs"

Dans cet exemple, deux workers différents sont définis, chacun d'eux utilisant des configurations et jeux de connexions séparés.

Partage de workers

Le partage de workers intervient lorsque les URLs des workers s'entrecoupent, ce qui arrive lorsque l'URL d'un worker correspond au début de l'URL d'un autre worker défini plus loin dans le fichier de configuration. Dans l'exemple suivant,

ProxyPass "/apps" "http://backend.example.com/" timeout=60
ProxyPass "/examples" "http://backend.example.com/examples" timeout=10

le second worker n'est pas vraiment créé. C'est le premier worker qui est en fait utilisé. L'avantage de ceci réside dans le fait qu'il n'existe qu'un seul jeu de connexions, ces dernières étant donc réutilisées plus souvent. Notez que tous les attributs de configuration définis explicitement pour le deuxième worker seront ignorés, ce qui sera journalisé en tant qu'avertissement. Ainsi, dans l'exemple ci-dessus, la valeur de timeout retenue pour l'URL /exemples sera 60, et non 10 !

Si vous voulez empêcher le partage de workers, classez vos définitions de workers selon la longueur des URLs, de la plus longue à la plus courte. Si au contraire vous voulez favoriser ce partage, utilisez l'ordre de classement inverse. Voir aussi l'avertissement à propos de l'ordre de classement des directives ProxyPass.

Les workers définis explicitement sont de deux sortes : workers directs et workers de répartition (de charge). Ils supportent de nombreux attributs de configuration importants décrits dans la directive ProxyPass. Ces mêmes attributs peuvent aussi être définis via la directive ProxySet.

Le jeu d'options disponibles pour un worker direct dépend du protocole spécifié dans l'URL du serveur original. Les protocoles disponibles comprennent ajp, fcgi, ftp, http et scgi.

Les workers de répartition sont des workers virtuels qui utilisent les workers directs, connus comme faisant partie de leurs membres, pour le traitement effectif des requêtes. Chaque répartiteur peut comporter plusieurs membres. Lorsqu'il traite une requête, il choisit un de ses membres en fonction de l'algorithme de répartition de charge défini.

Un worker de répartition est créé si son URL de worker comporte balancer comme indicateur de protocole. L'URL du répartiteur permet d'identifier de manière unique le worker de répartition. La directive BalancerMember permet d'ajouter des membres au répartiteur.

Résolution DNS pour les domaines originaux

La résolution DNS s'effectue lorsque le socket vers le domaine original est créé pour la première fois. Lorsque la réutilisation des connexions est activée, chaque domaine d'arrière-plan n'est résolu qu'une seule fois pour chaque processus enfant, et cette résolution est mise en cache pour toutes les connexions ultérieures jusqu'à ce que le processus enfant soit recyclé. Ce comportement doit être pris en considération lorsqu'on planifie des tâches de maintenance du DNS impactant les domaines d'arrière-plan. Veuillez aussi vous reporter aux paramètres de la directive ProxyPass pour plus de détails à propos de la réutilisation des connexions.

Contrôler l'accès à votre mandataire

Vous pouvez restreindre l'accès à votre mandataire via le bloc de contrôle <Proxy> comme dans l'exemple suivant :

<Proxy "*">
  Require ip 192.168.0
</Proxy>

Pour plus de détails sur les directives de contrôle d'accès, voir la documentation du module mod_authz_host.

Restreindre l'accès de manière stricte est essentiel si vous mettez en oeuvre un mandataire direct (en définissant la directive ProxyRequests à "on"). Dans le cas contraire, votre serveur pourrait être utilisé par n'importe quel client pour accéder à des serveurs quelconques, tout en masquant sa véritable identité. Ceci représente un danger non seulement pour votre réseau, mais aussi pour l'Internet au sens large. Dans le cas de la mise en oeuvre d'un mandataire inverse (en utilisant la directive ProxyPass avec ProxyRequests Off), le contrôle d'accès est moins critique car les clients ne peuvent contacter que les serveurs que vous avez spécifiés.

Voir aussi la variable d'environnement Proxy-Chain-Auth.

Ralentissement au démarrage

Si vous utilisez la directive ProxyBlock, les noms d'hôtes sont résolus en adresses IP puis ces dernières mises en cache au cours du démarrage à des fins de tests de comparaisons ultérieurs. Ce processus peut durer plusieurs secondes (ou d'avantage) en fonction de la vitesse à laquelle s'effectue la résolution des noms d'hôtes.

Mandataire en Intranet

Un serveur mandataire Apache httpd situé à l'intérieur d'un Intranet doit faire suivre les requêtes destinées à un serveur externe à travers le pare-feu de l'entreprise (pour ce faire, définissez la directive ProxyRemote de façon à ce qu'elle fasse suivre le protocole concerné vers le mandataire du pare-feu). Cependant, lorsqu'il doit accéder à des ressources situées dans l'Intranet, il peut se passer du pare-feu pour accéder aux serveurs. A cet effet, la directive NoProxy permet de spécifier quels hôtes appartiennent à l'Intranet et peuvent donc être accédés directement.

Les utilisateurs d'un Intranet ont tendance à oublier le nom du domaine local dans leurs requêtes WWW, et demandent par exemple "http://un-serveur/" au lieu de http://un-serveur.example.com/. Certains serveurs mandataires commerciaux acceptent ce genre de requête et les traitent simplement en utilisant un nom de domaine local implicite. Lorsque la directive ProxyDomain est utilisée et si le serveur est configuré comme mandataire, Apache httpd peut renvoyer une réponse de redirection et ainsi fournir au client l'adresse de serveur correcte, entièrement qualifiée. C'est la méthode à privilégier car le fichier des marque-pages de l'utilisateur contiendra alors des noms de serveurs entièrement qualifiés.

Ajustements relatifs au protocole

Pour les cas où mod_proxy envoie des requêtes vers un serveur qui n'implémente pas correctement les connexions persistantes ou le protocole HTTP/1.1, il existe deux variables d'environnement qui permettent de forcer les requêtes à utiliser le protocole HTTP/1.0 avec connexions non persistantes. Elles peuvent être définies via la directive SetEnv.

Il s'agit des variables force-proxy-request-1.0 et proxy-nokeepalive.

<Location "/buggyappserver/">
  ProxyPass "http://buggyappserver:7001/foo/"
  SetEnv force-proxy-request-1.0 1
  SetEnv proxy-nokeepalive 1
</Location>

A partir de la version 2.4.26 du serveur HTTP Apache, la définition de la variable d'environnement "no-proxy" permet de désactiver mod_proxy dans le traitement de la requête courante. Cette variable doit être définie via la directive SetEnvIf car la directive SetEnv n'est pas évaluée assez tôt.

Corps de requêtes

Certaines méthodes de requêtes comme POST comportent un corps de requête. Le protocole HTTP stipule que les requêtes qui comportent un corps doivent soit utiliser un codage de transmission fractionnée (chunked transfer encoding), soit envoyer un en-tête de requête Content-Length. Lorsqu'il fait suivre ce genre de requête vers le serveur demandé, mod_proxy_http s'efforce toujours d'envoyer l'en-tête Content-Length. Par contre, si la taille du corps est importante, et si la requête originale utilise un codage à fractionnement, ce dernier peut aussi être utilisé dans la requête montante. Ce comportement peut être contrôlé à l'aide de variables d'environnement. Ainsi, si elle est définie, la variable proxy-sendcl assure une compatibilité maximale avec les serveurs demandés en imposant l'envoi de l'en-tête Content-Length, alors que proxy-sendchunked diminue la consommation de ressources en imposant l'utilisation d'un codage à fractionnement.

Dans certaines circonstances, le serveur doit mettre en file d'attente sur disque les corps de requêtes afin de satisfaire le traitement demandé des corps de requêtes. Par exemple, cette mise en file d'attente se produira si le corps original a été envoyé selon un codage morcelé (et possède une taille importante), alors que l'administrateur a demandé que les requêtes du serveur d'arrière-plan soient envoyées avec l'en-tête Content-Length ou en HTTP/1.0. Cette mise en file d'attente se produira aussi si le corps de la requête contient déjà un en-tête Content-Length, alors que le serveur est configuré pour filtrer les corps des requêtes entrantes.

La directive LimitRequestBody ne s'applique qu'aux corps de requêtes que le serveur met en file d'attente sur disque.

En-têtes de requête du mandataire inverse

Lorsqu'il est configuré en mode mandataire inverse (en utilisant par exemple la directive ProxyPass), mod_proxy_http ajoute plusieurs en-têtes de requête afin de transmettre des informations au serveur demandé. Ces en-têtes sont les suivants :

X-Forwarded-For
L'adresse IP du client.
X-Forwarded-Host
L'hôte d'origine demandé par le client dans l'en-tête de requête HTTP Host.
X-Forwarded-Server
Le nom d'hôte du serveur mandataire.

Ces en-têtes doivent être utilisés avec précautions sur le serveur demandé, car ils contiendront plus d'une valeur (séparées par des virgules) si la requête originale contenait déjà un de ces en-têtes. Par exemple, vous pouvez utiliser %{X-Forwarded-For}i dans la chaîne de format du journal du serveur demandé pour enregistrer les adresses IP des clients originaux, mais il est possible que vous obteniez plusieurs adresses si la requête passe à travers plusieurs mandataires.

Voir aussi les directives ProxyPreserveHost et ProxyVia directives, qui permettent de contrôler d'autres en-têtes de requête.

Note : Si vous devez ajouter des en-têtes particuliers à la requête mandatée, utilisez la directive RequestHeader.

Directive BalancerGrowth

Description: | Nombre de membres supplémentaires pouvant être ajoutés après la configuration initiale
Syntaxe: | BalancerGrowth #
Défaut: | BalancerGrowth 5
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy
Compatibilité: | BalancerGrowth est disponible depuis la version 2.3.13 du serveur HTTP Apache

Cette directive permet de définir le nombre de membres pouvant être ajoutés au groupe de répartition de charge préconfiguré d'un serveur virtuel. Elle n'est active que si le groupe a été préconfiguré avec un membre au minimum.

Directive BalancerInherit

Description: | Héritage des membres du groupes de répartition de charge du mandataire définis au niveau du serveur principal
Syntaxe: | BalancerInherit On|Off
Défaut: | BalancerInherit On
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache.

Cette directive permet d'attribuer au serveur virtuel courant l'héritage des membres de groupes de répartition de charge définis au niveau du serveur principal. Elle ne doit pas être activée si vous utilisez la fonctionnalité de modifications dynamiques du gestionnaire de répartition de charge (Balancer Manager) pour éviter des problèmes et des comportements inattendus.

Les définitions au niveau du serveur principal constituent les définitions par défaut au niveau des serveurs virtuels.

Directive BalancerMember

Description: | Ajoute un membre à un groupe de répartition de charge
Syntaxe: | BalancerMember [balancerurl] url [clé=valeur [clé=valeur ...]]
Contexte: | répertoire
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Disponible depuis la version 2.2 du serveur HTTP Apache.

Cette directive permet d'ajouter un membre à un groupe de répartition de charge. Elle peut se trouver dans un conteneur <Proxy balancer://...>, et accepte tous les paramètres de paires clé/valeur que supporte la directive ProxyPass.

La directive BalancerMember accepte un paramètre supplémentaire : loadfactor. Il s'agit du facteur de charge du membre - un nombre décimal entre 1.0 (valeur par défaut) et 100.0, qui définit la charge à appliquer au membre en question.

L'argument balancerurl n'est requis que s'il ne se trouve pas dèjà dans la directive de conteneur <Proxy balancer://...>. Il correspond à l'URL d'un répartiteur de charge défini par une directive ProxyPass.

La partie chemin de l'URL du répartiteur dans toute directive de conteneur <Proxy balancer://...> est ignorée.

En particulier, le slash de fin de l'URL d'un BalancerMember doit être supprimé.

Directive BalancerPersist

Description: | Tente de conserver les changements effectués par le gestionnaire de répartition de charge après un redémarrage du serveur.
Syntaxe: | BalancerPersist On|Off
Défaut: | BalancerPersist Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy
Compatibilité: | BalancerPersist n'est disponible qu'à partir de la version 2.4.4 du serveur HTTP Apache.

Cette directive permet de conserver le contenu de l'espace mémoire partagé associé aux répartiteurs de charge et à leurs membres après un redémarrage du serveur. Ces modifications locales ne sont ainsi pas perdues lors des transitions d'état dues à un redémarrage.

Directive NoProxy

Description: | Serveurs, domaines ou réseaux auquels on se connectera directement
Syntaxe: | NoProxy domaine [domaine] ...
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

Cette directive n'a d'utilité que pour les serveurs mandataires Apache httpd au sein d'Intranets. La directive NoProxy permet de spécifier une liste de sous-réseaux, d'adresses IP, de serveurs et/ou de domaines séparés par des espaces. Une requête pour un serveur qui correspond à un ou plusieurs critères sera toujours servie par ce serveur directement, sans être redirigée vers le(s) serveur(s) mandataire(s) défini(s) par la directive ProxyRemote.

Exemple

ProxyRemote  "*"  "http://firewall.example.com:81"
NoProxy         ".example.com" "192.168.112.0/21"

Le type des arguments serveur de la directive NoProxy appartiennent à la liste suivante :

Domaine

Un domaine est ici un nom de domaine DNS partiellement qualifié précédé d'un point. Il représente une liste de serveurs qui appartiennent logiquement au même domaine ou à la même zonz DNS (en d'autres termes, les nom des serveurs se terminent tous par domaine).

Exemple

.com .example.org.

Pour faire la distinction entre domaines et nom d'hôtes (des points de vue à la fois syntaxique et sémantique, un domaine DNS pouvant aussi avoir un enregistrement DNS de type A !), les domaines sont toujours spécifiés en les préfixant par un point.

Note

Les comparaisons de noms de domaines s'effectuent sans tenir compte de la casse, et les parties droites des Domaines sont toujours censées correspondre à la racine de l'arborescence DNS, si bien que les domaines .ExEmple.com et .example.com. (notez le point à la fin du nom) sont considérés comme identiques. Comme une comparaison de domaines ne nécessite pas de recherche DNS, elle est beaucoup plus efficace qu'une comparaison de sous-réseaux.

Sous-réseau

Un Sous-réseau est une adresse internet partiellement qualifiée sous forme numérique (quatre nombres séparés par des points), optionnellement suivie d'un slash et du masque de sous-réseau spécifiant le nombre de bits significatifs dans le Sous-réseau. Il représente un sous-réseau de serveurs qui peuvent être atteints depuis la même interface réseau. En l'absence de masque de sous-réseau explicite, il est sous-entendu que les digits manquants (ou caractères 0) de fin spécifient le masque de sous-réseau (Dans ce cas, le masque de sous-réseau ne peut être qu'un multiple de 8). Voici quelques exemples :

192.168 ou 192.168.0.0
le sous-réseau 192.168.0.0 avec un masque de sous-réseau implicite de 16 bits significatifs (parfois exprimé sous la forme 255.255.0.0)
192.168.112.0/21
le sous-réseau 192.168.112.0/21 avec un masque de sous-réseau implicite de 21 bits significatifs (parfois exprimé sous la forme255.255.248.0)

Comme cas extrêmes, un Sous-réseau avec un masque de sous-réseau de 32 bits significatifs est équivalent à une adresse IP, alors qu'un Sous-réseau avec un masque de sous-réseau de 0 bit significatif (c'est à dire 0.0.0.0/0) est identique à la constante _Default_, et peut correspondre à toute adresse IP.

Adresse IP

Une Adresse IP est une adresse internet pleinement qualifiée sous forme numérique (quatre nombres séparés par des points). En général, cette adresse représente un serveur, mais elle ne doit pas nécessairement correspondre à un nom de domaine DNS.

Exemple

192.168.123.7

Note

Une Adresse IP ne nécessite pas de résolution DNS, et peut ainsi s'avérer plus efficace quant aux performances d'Apache.

Nom de serveur

Un Nom de serveur est un nom de domaine DNS pleinement qualifié qui peut être résolu en une ou plusieurs adresses IP par le service de noms de domaines DNS. Il représente un hôte logique (par opposition aux Domaines, voir ci-dessus), et doit pouvoir être résolu en une ou plusieurs adresses IP (ou souvent en une liste d'hôtes avec différentes adresses IP).

Exemples

prep.ai.example.edu
www.example.org

Note

Dans de nombreuses situations, il est plus efficace de spécifier une adresse IP qu'un Nom de serveur car cela évite d'avoir à effectuer une recherche DNS. La résolution de nom dans Apache httpd peut prendre un temps très long lorsque la connexion avec le serveur de noms utilise une liaison PPP lente.

Les comparaisons de Nom de serveur s'effectuent sans tenir compte de la casse, et les parties droites des Noms de serveur sont toujours censées correspondre à la racine de l'arborescence DNS, si bien que les domaines WWW.ExEmple.com et www.example.com. (notez le point à la fin du nom) sont considérés comme identiques.

Voir aussi

  • Problèmes liés au DNS

Directive <Proxy>

Description: | Conteneur de directives s'appliquant à des ressources mandatées
Syntaxe: | <Proxy url-avec-jokers> ...</Proxy>
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

Les directives situées dans une section <Proxy> ne s'appliquent qu'au contenu mandaté concerné. Les jokers de style shell sont autorisés.

Par exemple, les lignes suivantes n'autoriseront à accéder à un contenu via votre serveur mandataire que les hôtes appartenant à votre-reseau.example.com :

<Proxy "*">
  Require host votre-reseau.example.com
</Proxy>

Dans l'exemple suivant, tous les fichiers du répertoire foo de example.com seront traités par le filtre INCLUDES lorsqu'ils seront envoyés par l'intermédiaire du serveur mandataire :

<Proxy "http://example.com/foo/*">
  SetOutputFilter INCLUDES
</Proxy>

Différences avec la section de configuration Location

Une URL d'arrière-plan sera concernée par le conteneur Proxy si elle commence par la url-avec-jokers, même si le dernier segment de chemin de la directive ne correspond qu'à un préfixe de segment dee chemin de l'URL d'arrière-plan. Par exemple, <Proxy "http://example.com/foo"> correspondra entre autres aux URLs http://example.com/foo, http://example.com/foo/bar, et http://example.com/foobar. La correspondance de l'URL finale diffère du comportement de la section <Location> qui, pour le cas de cette note, traitera le segment de chemin final comme s'il se terminait par un slash.

Pour un contrôle plus fin de la correspondance des URL, voir la directive <ProxyMatch>.

Voir aussi

  • <ProxyMatch>

Directive ProxyAddHeaders

Description: | Ajoute des informations à propos du mandataire aux en-têtes X-Forwarded-*
Syntaxe: | ProxyAddHeaders Off|On
Défaut: | ProxyAddHeaders On
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Disponible depuis la version 2.3.10

Cette directive permet de passer au serveur d'arrière-plan des informations à propos du mandataire via les en-têtes HTTP X-Forwarded-For, X-Forwarded-Host et X-Forwarded-Server.

Utilité

Cette option n'est utile que dans le cas du mandat HTTP traité par mod_proxy_http.

Directive ProxyBadHeader

Description: | Détermine la manière de traiter les lignes d'en-tête incorrectes d'une réponse
Syntaxe: | ProxyBadHeader IsError|Ignore|StartBody
Défaut: | ProxyBadHeader IsError
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

La directive ProxyBadHeader permet de déterminer le comportement de mod_proxy lorsqu'il reçoit des lignes d'en-tête de réponse dont la syntaxe n'est pas valide (c'est à dire ne contenant pas de caractère ':') en provenance du serveur original. Les arguments disponibles sont :

IsError
Annule la requête et renvoie une réponse de code 502 (mauvaise passerelle). C'est le comportement par défaut.
Ignore
Traite les lignes d'en-tête incorrectes comme si elles n'avaient pas été envoyées.
StartBody
A la réception de la première ligne d'en-tête incorrecte, les autres en-têtes sont lus et ce qui reste est traité en tant que corps. Ceci facilite la prise en compte des serveurs d'arrière-plan bogués qui oublient d'insérer une ligne vide entre les en-têtes et le corps.

Directive ProxyBlock

Description: | Termes, serveurs ou domaines bloqués par le mandataire
Syntaxe: | ProxyBlock *|terme|serveur|domaine [terme|serveur|domaine] ...
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

La directive ProxyBlock permet de spécifier une liste de termes, serveurs et/ou domaines, séparés par des espaces. Les requêtes de documents HTTP, HTTPS, FTP vers des sites dont les noms contiennent des termes, noms de serveur ou domaine correspondants seront bloqués par le serveur mandataire. La module proxy va aussi tenter de déterminer les adresses IP des éléments de la liste qui peuvent correspondre à des noms d'hôtes au cours du démarrage, et les mettra en cache à des fins de comparaisons ultérieures. Ceci peut ralentir le démarrage du serveur.

Exemple

ProxyBlock "news.example.com" "auctions.example.com" "friends.example.com"

Notez qu'example suffirait aussi pour atteindre ces sites.

Hosts conviendrait aussi s'il était référencé par adresse IP.

Notez aussi que

ProxyBlock "*"

bloque les connexions vers tous les sites.

Directive ProxyDomain

Description: | Nom de domaine par défaut pour les requêtes mandatées
Syntaxe: | ProxyDomain Domaine
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

Cette directive n'a d'utilité que pour les serveurs mandataires Apache httpd au sein d'un Intranet. La directive ProxyDomain permet de spécifier le domaine par défaut auquel le serveur mandataire apache appartient. Si le serveur reçoit une requête pour un hôte sans nom de domaine, il va générer une réponse de redirection vers le même hôte suffixé par le Domaine spécifié.

Exemple

ProxyRemote  "*"  "http://firewall.example.com:81"
NoProxy         ".example.com" "192.168.112.0/21"
ProxyDomain     ".example.com"

Directive ProxyErrorOverride

Description: | Outrepasser les pages d'erreur pour les contenus mandatés
Syntaxe: | ProxyErrorOverride On|Off
Défaut: | ProxyErrorOverride Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy

Cette directive est utile pour les configurations de mandataires inverses, lorsque vous souhaitez que les pages d'erreur envoyées aux utilisateurs finaux présentent un aspect homogène. Elle permet aussi l'inclusion de fichiers (via les SSI de mod_include) pour obtenir le code d'erreur et agir en conséquence (le comportement par défaut afficherait la page d'erreur du serveur mandaté, alors que c'est le message d'erreur SSI qui sera affiché si cette directive est à "on").

Cette directive n'affecte pas le traitement des réponses informatives (1xx), de type succès normal (2xx), ou de redirection (3xx).

Directive ProxyIOBufferSize

Description: | Détermine la taille du tampon interne de transfert de données
Syntaxe: | ProxyIOBufferSize octets
Défaut: | ProxyIOBufferSize 8192
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

La directive ProxyIOBufferSize permet d'ajuster la taille du tampon interne utilisé comme bloc-note pour les transferts de données entre entrée et sortie. La taille minimale est de 512 octets.

Dans la plupart des cas, il n'y a aucune raison de modifier cette valeur.

Si elle est utilisée avec AJP, cette directive permet de définir la taille maximale du paquet AJP en octets. Si la valeur spécifiée est supérieure à 65536, elle est corrigée et prend la valeur 65536. Si vous ne conservez pas la valeur par défaut, vous devez aussi modifier l'attribut packetSize de votre connecteur AJP du côté de Tomcat ! L'attribut packetSize n'est disponible que dans Tomcat 5.5.20+ et 6.0.2+.

Il n'est normalement pas nécessaire de modifier la taille maximale du paquet. Des problèmes ont cependant été rapportés avec la valeur par défaut lors de l'envoi de certificats ou de chaînes de certificats.

Directive <ProxyMatch>

Description: | Conteneur de directives s'appliquant à des ressources mandatées correspondant à une expression rationnelle
Syntaxe: | <ProxyMatch regex> ...</ProxyMatch>
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

La directive <ProxyMatch> est identique à la directive <Proxy>, à l'exception qu'elle définit les URLs auxquelles elle s'applique en utilisant une expression rationnelle.

A partir de la version 2.4.8, les groupes nommés et les références arrières sont extraits et enregistrés dans l'environnement avec leur nom en majuscules et préfixé par "MATCH_". Ceci permet de référencer des URLs dans des expressions ou au sein de modules comme mod_rewrite. Pour éviter toute confusion, les références arrières numérotées (non nommées) sont ignorées. Vous devez utiliser à la place des groupes nommés.

<ProxyMatch "^http://(?<sitename>[^/]+)">
    Require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example
</ProxyMatch>

Voir aussi

  • <Proxy>

Directive ProxyMaxForwards

Description: | Nombre maximum de mandataires à travers lesquelles une requête peut être redirigée
Syntaxe: | ProxyMaxForwards nombre
Défaut: | ProxyMaxForwards -1
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Comportement par défaut modifié dans 2.2.7

La directive ProxyMaxForwards permet de spécifier le nombre maximum de mandataires à travers lesquels une requête peut passer dans le cas où la la requête ne contient pas d'en-tête Max-Forwards. Ceci permet de se prémunir contre les boucles infinies de mandataires ou contre les attaques de type déni de service.

Exemple

ProxyMaxForwards 15

Notez que la définition de la directive ProxyMaxForwards constitue une violation du protocole HTTP/1.1 (RFC2616), qui interdit à un mandataire de définir Max-Forwards si le client ne l'a pas fait lui-même. Les versions précédentes d'Apache httpd la définissaient systématiquement. Une valeur négative de ProxyMaxForwards, y compris la valeur par défaut -1, implique un comportement compatible avec le protocole, mais vous expose aux bouclages infinis.

Directive ProxyPass

Description: | Référencer des serveurs distants depuis l'espace d'URLs du serveur local
Syntaxe: | ProxyPass [chemin] !|url [clé=valeur [clé=valeur ...]] [nocanon] [interpolate] [noquery]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Les sockets de style Unix (Unix Domain Socket - UDS) sont supportés à partir de la version 2.4.7 du serveur HTTP Apache

Cette directive permet de référencer des serveurs distants depuis l'espace d'URLs du serveur local. Le serveur local n'agit pas en tant que mandataire au sens conventionnel, mais plutôt comme miroir du serveur distant. Le serveur local est souvent nommé mandataire inverse ou passerelle. L'argument chemin est le nom d'un chemin virtuel local ; url est une URL partielle pour le serveur distant et ne doit pas contenir de chaîne d'arguments.

Il est fortement recommandé de revoir le concept de Worker avant d'aller plus loin.
Cette directive n'est pas supportée au sein des sections <Directory> et <Files>.
En général, la directive ProxyRequests doit être définie à off lorsqu'on utilise la directive ProxyPass.

Les sockets de style Unix sont supportés à partir de la version 2.4.7 du serveur HTTP Apache ; pour utiliser cette fonctionnalité, il suffit d'utiliser une URL cible préfixée par unix:/path/lis.sock|. Par exemple, pour mandater HTTP et cibler l'UDS /home/www/socket, vous devez utiliser unix:/home/www.socket|http://localhost/whatever/.

Note :Le chemin associé à l'URL unix: tient compte de la directive DefaultRuntimeDir.

Lorsque cette directive est utilisée dans une section <Location>, le premier argument est omis et le répertoire local est obtenu à partir de l'argument de la directive <Location>. Il en est de même à l'intérieur d'une section <LocationMatch>, mais le résultat ne sera probablement pas celui attendu car ProxyPassReverse va interpréter l'expression rationnelle littéralement comme un chemin ; si besoin est dans ce cas, définissez la directive ProxyPassReverse en dehors de la section, ou dans une section <Location> séparée.

Supposons que le serveur local a pour adresse http://example.com/ ; alors la ligne

<Location "/mirror/foo/">
    ProxyPass "http://backend.example.com/"
</Location>

va convertir en interne toute requête pour http://example.com/miroir/foo/bar en une requête mandatée pour http://backend.example.com/bar.

Si vous avez besoin d'un configuration de mandataire inverse plus souple, reportez-vous à la documentaion de la directive RewriteRule et son drapeau [P].

La syntaxe alternative suivante est valide, bien qu'elle puisse induire une dégradation des performances lorsqu'elle est présente en très grand nombre. Elle possède l'avantage de permettre un contrôle dynamique via l'interface Balancer Manager :

ProxyPass "/miroir/foo/" "http://backend.example.com/"

Si le premier argument se termine par un slash /, il doit en être de même pour le second argument et vice versa. Dans le cas contraire, il risque de manquer des slashes nécessaires dans la requête résultante vers le serveur d'arrière-plan et les résulats ne seront pas ceux attendus.

Le drapeau ! permet de soustraire un sous-répertoire du mandat inverse, comme dans l'exemple suivant :

<Location "/mirror/foo/">
    ProxyPass "http://backend.example.com/"
</Location>
<Location "/mirror/foo/i">
    ProxyPass "!"
</Location>
ProxyPass "/mirror/foo/i" "!"
ProxyPass "/mirror/foo" "http://backend.example.com"

va mandater toutes les requêtes pour /miroir/foo vers backend.example.com, sauf les requêtes pour /miroir/foo/i.

Ordre de classement des directives ProxyPass

Les directives ProxyPass et ProxyPassMatch sont évaluées dans l'ordre de leur apparition dans le fichier de configuration. La première règle qui correspond s'applique. Vous devez donc en général classer les règles ProxyPass qui entrent en conflit de l'URL la plus longue à la plus courte. Dans le cas contraire, les règles situées après une règle dont l'URL correspond au début de leur propre URL seront ignorées. Notez que tout ceci est en relation avec le partage de workers. Par contre, on ne peut placer qu'une seule directive ProxyPass dans une section Location, et c'est la section la plus spécifique qui l'emportera.

Pour les mêmes raisons, les exclusions doivent se situer avant les directives ProxyPass générales. A partir de la version 2.4.26 du serveur HTTP Apache, la variable d'environnement "no-proxy" est une alternative aux exclusions et constitue le seul moyen de configurer une exclusion pour une directive ProxyPass dans le contexte d'une section Location. Cette variable doit être définie via la directive SetEnvIf car la directive SetEnv n'est pas évaluée assez tôt.

ProxyPass clé=valeur Paramètres

Depuis la version 2.1 du serveur HTTP Apache, mod_proxy supporte les groupements de connexions vers un serveur d'arrière-plan. Les connexions créées à la demande peuvent être enregistrées dans un groupement pour une utilisation ultérieure. La taille du groupe ainsi que d'autres caractéristiques peuvent être définies via la directive ProxyPass au moyen de paramètres clé=valeur dont la description fait l'objet des tableaux ci-dessous.

Nombre maximum de connexions vers l'arrière-plan

Par défaut, mod_proxy permet et met en réserve le nombre maximum de connexions pouvant être utilisées simultanément par le processus enfant concerné du serveur web. Le paramètre max permet de réduire cette valeur par défaut. Le jeu de connexions est maintenu au niveau de chaque processus enfant du serveur web, max et les autres réglages n'étant pas coordonnés entre ces différents processus, sauf bien entendu lorsqu'un seul processus enfant n'est autorisé par la configuration ou le MPM utilisé.

Le paramètre ttl, quant à lui, permet de définir une durée de vie optionnelle ; les connexions qui n'ont pas été utilisées pendant au moins ttl secondes seront fermées. ttl permet aussi d'empêcher l'utilisation d'une connexion susceptible d'être fermée suite à une fin de vie de connexion persistante sur le serveur d'arrière-plan.

Exemple

ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
Paramètres de worker (directive BalancerMember)
Paramètre | Défaut | Description
min | 0 | Nombre minimum d'entrées dans le pool de connexions, distinct du nombre de connexions effectif. La valeur par défaut ne doit être modifiée que dans des circonstances particulières où la mémoire associée aux connexions avec le serveur d'arrière-plan doit être préallouée ou réservée dans le tas.
max | 1...n | Nombre maximum de connexions autorisées vers le serveur d'arrière-plan. La valeur par défaut correspond au nombre de threads par processus pour le MPM (Module Multi Processus) actif. La valeur sera toujours 1 pour le MPM Prefork, alors qu'elle dépendra de la définition de la directive ThreadsPerChild pour les autres MPMs.
smax | max | Les entrées du pool de connexions conservées au delà de cette limite sont libérées au cours de certaines opérations si elles n'ont pas été utilisées au cours de leur durée de vie, définie par le paramètre ttl. Si l'entrée du pool de connexions est associée à une connexion, cette dernière sera fermée. La valeur par défaut ne doit être modifiée que dans des circonstances particulières où les entrées du pool de connexions et toutes connexions associées qui ont dépassé leur durée de vie doivent être libérées ou fermées de manière plus autoritaire.
acquire - Cette clé permet de définir le délai maximum d'attente pour une connexion libre dans le jeu de connexions, en millisecondes. S'il n'y a pas de connexion libre dans le jeu, Apache httpd renverra l'état SERVER_BUSY au client.
connectiontimeout | timeout | Délai d'attente d'une connexion en secondes. La durée en secondes pendant laquelle Apache httpd va attendre pour l'établissement d'une connexion vers le serveur d'arrière-plan. Le délai peut être spécifié en millisecondes en ajoutant le suffixe ms.
disablereuse | Off | Vous pouvez utiliser cette clé pour forcer mod_proxy à fermer immédiatement une connexion vers le serveur d'arrière-plan après utilisation, et ainsi désactiver le jeu de connexions permanentes vers ce serveur. Ceci peut s'avérer utile dans des situations où un pare-feu situé entre Apache httpd et le serveur d'arrière-plan (quelque soit le protocole) interrompt des connexions de manière silencieuse, ou lorsque le serveur d'arrière-plan lui-même est accessible par rotation de DNS (round-robin DNS). Lorsque la réutilisation des connexions est activée, chaque domaine d'arrière-plan n'est résolu (via une requête DNS) qu'une seule fois par chaque processus enfant et mis en cache pour toutes les connexions ultérieures jusqu'au recyclage du processus concerné. Pour désactiver la réutilisation du jeu de connexions, définissez cette clé à On.
enablereuse | On | Ce paramètre est utilisé par les gestionnaires de protocole pour lesquels la réutilisation des connexions est optionnelle (comme mod_proxy_fcgi). C'est le contraire du paramètre 'disablereuse' ci-dessus, et il est supporté par les versions 2.4.11 et supérieures du serveur HTTP Apache.
flushpackets | off | Permet de définir si le module mandataire doit vider automatiquement le tampon de sortie après chaque tronçon de données. 'off' signifie que le tampon sera vidé si nécessaire ; 'on' signifie que le tampon sera vidé après chaque envoi d'un tronçon de données, et 'auto' que le tampon sera vidé après un délai de 'flushwait' millisecondes si aucune entrée n'est reçue. Actuellement, cette clé n'est supportée que par mod_proxy_ajp et mod_proxy_fcgi.
flushwait | 10 | Le délai d'attente pour une entrée additionnelle, en millisecondes, avant le vidage du tampon en sortie dans le cas où 'flushpackets' est à 'auto'.
iobuffersize | 8192 | Permet de définir la taille du tampon d'entrées/sorties du bloc-notes interne. Cette clé vous permet d'outrepasser la directive ProxyIOBufferSize pour un serveur cible spécifique. La valeur doit être au minimum 512 ou définie à 0 pour la valeur par défaut du système de 8192.
keepalive Off

Cette clé doit être utilisée lorsque vous avez un pare-feu entre Apache httpd et le serveur d'arrière-plan, et si ce dernier tend à interrompre les connexions inactives. Cette clé va faire en sorte que le système d'exploitation envoie des messages KEEP_ALIVE sur chacune des connexions inactives et ainsi éviter la fermeture de la connexion par le pare-feu. Pour conserver les connexions persistantes, definissez cette propriété à On.

La fréquence de vérification des connexions TCP persistantes initiale et subséquentes dépend de la configuration globale de l'OS, et peut atteindre 2 heures. Pour être utile, la fréquence configurée dans l'OS doit être inférieure au seuil utilisé par le pare-feu.

lbset | 0 | Définit le groupe de répartition de charge dont le serveur cible est membre. Le répartiteur de charge va essayer tous les membres d'un groupe de répartition de charge de numéro inférieur avant d'essayer ceux dont le groupe possède un numéro supérieur.
ping | 0 | Avec la clé Ping, le serveur web va "tester" la connexion vers le serveur d'arrière-plan avant de transmettre la requête. Avec AJP, mod_proxy_ajp envoie une requête CPING sur la connexion ajp13 (implémenté sur Tomcat 3.3.2+, 4.1.28+ et 5.0.13+). Avec HTTP, mod_proxy_http envoie 100-Continue au serveur d'arrière-plan (seulement avecHTTP/1.1 - pour les serveurs d'arrière-plan non HTTP/1.1, cette clé ne produit aucun effet). Dans les deux cas, ce paramètre correspond au délai en secondes pour l'attente de la réponse. Cette fonctionnalité a été ajoutée pour éviter les problèmes avec les serveurs d'arrière-plan bloqués ou surchargés. Le trafic réseau peut s'en trouver augmenté en fonctionnement normal, ce qui peut poser problème, mais peut s'en trouver diminué dans les cas où les noeuds de cluster sont arrêtés ou surchargés. Le délai peut aussi être défini en millisecondes en ajoutant le suffixe ms.
receivebuffersize | 0 | Définit la taille du tampon réseau explicite (TCP/IP) pour les connexions mandatées. Cette clé vous permet d'outrepasser la directive ProxyReceiveBufferSize pour un serveur cible spécifique. Sa valeur doit être au minimum 512 ou définie à 0 pour la valeur par défaut du système.
redirect - Route pour la redirection du serveur cible. Cette valeur est en général définie dynamiquement pour permettre une suppression sécurisée du noeud du cluster. Si cette clé est définie, toutes les requêtes sans identifiant de session seront redirigées vers le membre de groupe de répartition de charge dont la route correspond à la valeur de la clé.
retry | 60 | Délai entre deux essais du serveur cible du jeu de connexions en secondes. Si le serveur cible du jeu de connexions vers le serveur d'arrière-plan est dans un état d'erreur, Apache httpd ne redirigera pas de requête vers ce serveur avant l'expiration du délai spécifié. Ceci permet d'arrêter le serveur d'arrière-plan pour maintenance, et de le remettre en ligne plus tard. Une valeur de 0 implique de toujours essayer les serveurs cibles dans un état d'erreur sans délai.
route - La route du serveur cible lorsqu'il est utilisé au sein d'un répartiteur de charge. La route est une valeur ajoutée à l'identifiant de session.
status - Valeur constituée d'une simple lettre et définissant l'état initial de ce serveur cible.
D: le serveur cible est désactivé et n'accepte aucune requête.
S: le serveur cible est arrêté.
I: le serveur cible est en mode "erreurs ignorées", et sera toujours considéré comme disponible.
H: le serveur cible est en mode d'attente et ne sera utilisé que si aucun autre serveur n'est disponible.
E: le serveur cible est en erreur.
N: le serveur cible est en mode vidage, n'acceptera que les sessions persistantes qui lui appartiennent, et refusera toutes les autres requêtes.
Une valeur d'état peut être définie (ce qui correspond au comportement par défaut) en préfixant la valeur par '+', ou annulée en préfixant la valeur par '-'. Ainsi, la valeur 'S-E' définit l'état de ce serveur cible à "arrêté" et supprime le drapeau "en-erreur".
timeout | ProxyTimeout | Délai d'attente de la connexion en secondes. Le nombre de secondes pendant lesquelles Apache httpd attend l'envoi de données vers le serveur d'arrière-plan.
ttl - Durée de vie des connexions inactives et des entrées du pool de connexions associées en secondes. Une fois cette limite atteinte, une connexion ne sera pas réutilisée ; elle sera fermée après un délai variable.
flusher flush

Nom du fournisseur utilisé par mod_proxy_fdpass. Voir la documentation de ce module pour plus de détails.

secret -

Le mot de passe utilisé par mod_proxy_ajp. Voir la documentation de ce module pour plus de détails.

upgrade WebSocket

Le protocol accepté par mod_proxy_wstunnel dans l'en-tête Upgrade. Voir la documentation de ce module pour plus de détails.

Si l'URL de la directive Proxy débute par balancer:// (par exemple: balancer://cluster, toute information relative au chemin est ignorée), alors un serveur cible virtuel ne communiquant pas réellement avec le serveur d'arrière-plan sera créé. Celui-ci sera en fait responsable de la gestion de plusieurs serveurs cibles "réels". Dans ce cas, un jeu de paramètres particuliers s'applique à ce serveur cible virtuel. Voir mod_proxy_balancer pour plus d'informations à propos du fonctionnement du répartiteur de charge.

Paramètres du répartiteur
Paramètre | Défaut | Description
lbmethod | byrequests | Méthode de répartition de charge utilisée. Permet de sélectionner la méthode de planification de la répartition de charge à utiliser. La valeur est soit byrequests, pour effectuer un décompte de requêtes pondérées, soit bytraffic, pour effectuer une répartition en fonction du décompte des octets transmis, soit bybusyness, pour effectuer une répartition en fonction des requêtes en attente. La valeur par défaut est byrequests.
maxattempts | 1 de moins que le nombre de workers, ou 1 avec un seul worker | Nombre maximum d'échecs avant abandon.
nofailover | Off | Si ce paramètre est défini à On, la session va s'interrompre si le serveur cible est dans un état d'erreur ou désactivé. Définissez ce paramètre à On si le serveur d'arrière-plan ne supporte pas la réplication de session.
stickysession - Nom de session persistant du répartiteur. La valeur est généralement du style JSESSIONID ou PHPSESSIONID, et dépend du serveur d'application d'arrière-plan qui supporte les sessions. Si le serveur d'application d'arrière-plan utilise un nom différent pour les cookies et les identifiants codés d'URL (comme les conteneurs de servlet), séparez-les par le caractère '|'. La première partie contient le cookie et la seconde le chemin.
Disponible depuis la version 2.4.4 du serveur HTTP Apache.
stickysessionsep "." Définit le caractère de séparation dans le cookie de session. Certains serveurs d'application d'arrière-plan n'utilisent pas le caractère '.' comme séparateur. Par exemple le serveur Oracle Weblogic utilise le caractère '!'. Cette option permet d'attribuer au caractère de séparation la valeur appropriée. Si elle est définie à 'Off', aucun caractère de séparation n'est utilisé.
scolonpathdelim | Off | Si ce paramètre est défini à On, le caractère ';' sera utilisé comme séparateur de chemin de session persistante additionnel. Ceci permet principalement de simuler le comportement de mod_jk lorsqu'on utilise des chemins du style JSESSIONID=6736bcf34;foo=aabfa.
timeout | 0 | Délai du répartiteur en secondes. Si ce paramètre est défini, sa valeur correspond à la durée maximale d'attente pour un serveur cible libre. Le comportement par défaut est de ne pas attendre.
failonstatus - Une liste de codes d'état HTTP séparés par des virgules. Si ce paramètre est présent, le worker se mettra en erreur si le serveur d'arrière-plan renvoie un des codes d'état spécifiés dans la liste. La récupération du worker s'effectue comme dans le cas des autres erreurs de worker.
failontimeout Off Si ce paramètre est défini à "On", un délai d'attente dépassé en entrée/sortie après envoi d'une requête au serveur d'arrière-plan va mettre le processus en état d'erreur. La sortie de cet état d'erreur se passe de la même façon que pour les autres erreurs.
Disponible à partir de la version 2.4.5 du serveur HTTP Apache.
nonce <auto> Le nombre à usage unique de protection utilisé dans la page de l'application balancer-manager. Par défaut, la protection de la page est assurée par un nombre à usage unique automatique à base d'UUID. Si une valeur est précisée, elle sera utilisée comme nombre à usage unique. La valeur None désactive la vérification du nombre à usage unique.

Note

En plus du nombre à usage unique, la page de l'application balancer-manager peut être protégée par une ACL.

growth | 0 | Nombre de membres supplémentaires que l'on peut ajouter à ce répartiteur en plus de ceux définis au niveau de la configuration.
forcerecovery On Force la relance immédiate de tous les membres sans tenir compte de leur paramètre retry dans le cas où ils sont tous en état d'erreur. Il peut cependant arriver qu'un membre déjà surchargé entre dans une situation critique si la relance de tous les membres est forcée sans tenir compte du paramètre retry de chaque membre. Dans ce cas, définissez ce paramètre à Off.
Disponible depuis la version 2.4.2 du serveur HTTP Apache.

Exemple de configuration d'un répartiteur de charge

ProxyPass "/special-area" "http://special.example.com" smax=5 max=10
ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On
<Proxy "balancer://mycluster">
    BalancerMember "ajp://1.2.3.4:8009"
    BalancerMember "ajp://1.2.3.5:8009" loadfactor=20
    # Less powerful server, don't send as many requests there,
    BalancerMember "ajp://1.2.3.6:8009" loadfactor=5
</Proxy>

Configuration d'un serveur cible de réserve qui ne sera utilisé que si aucun autre serveur cible n'est disponible

ProxyPass "/" "balancer://hotcluster/"
<Proxy "balancer://hotcluster">
    BalancerMember "ajp://1.2.3.4:8009" loadfactor=1
    BalancerMember "ajp://1.2.3.5:8009" loadfactor=2.25
    # The server below is on hot standby
    BalancerMember "ajp://1.2.3.6:8009" status=+H
    ProxySet lbmethod=bytraffic
</Proxy>

Mots-clés additionnels de ProxyPass

Normalement, mod_proxy va mettre sous leur forme canonique les URLs traitées par ProxyPass. Mais ceci peut être incompatible avec certains serveurs d'arrière-plan, et en particulier avec ceux qui utilisent PATH_INFO. Le mot-clé optionnel nocanon modifie ce comportement et permet de transmettre le chemin d'URL sous sa forme brute au serveur d'arrière-plan. Notez que ceci peut affecter la sécurité de votre serveur d'arrière-plan, car la protection limitée contre les attaques à base d'URL que fournit le mandataire est alors supprimée.

Par défaut, mod_proxy inclut la chaîne de paramètres lors de la génération de la variable d'environnement SCRIPT_FILENAME. Le mot-clé optionnel noquery (disponible à partir de la version 2.4.1) permet d'exclure cette chaîne.

Lorsque la directive ProxyPass est utilisée à l'intérieur d'une section <Location>, le premier argument est omis et le répertoire local est obtenu à partir de la section <Location>. Il en sera de même dans une section <LocationMatch> ; cependant, ProxyPass n'interprète pas les expressions rationnelles, et il sera ici nécessaire d'utiliser la directive ProxyPassMatch à la place.

Cette directive ne peut pas être placée dans une section <Directory> ou <Files>.

Si vous avez besoin d'un configuration de mandataire inverse plus souple, reportez-vous à la documentaion de la directive RewriteRule et son drapeau [P].

Le mot-clé optionnel interpolate, en combinaison avec la directive ProxyPassInterpolateEnv, permet à ProxyPass d'interpoler les variables d'environnement à l'aide de la syntaxe ${VARNAME}. Notez que de nombreuses variables d'environnement standard dérivées de CGI n'existeront pas lorsque l'interpolation se produit ; vous devrez alors encore avoir avoir recours à mod_rewrite pour des règles complexes. Notez aussi que l'interpolation n'est pas supportée dans la partie protocole d'une URL. La détermination dynamique du protocole peut être effectuée à l'aide de mod_rewrite comme dans l'exemple suivant :

RewriteEngine On

RewriteCond "%{HTTPS}" =off
RewriteRule "". "-" [E=protocol:http]
RewriteCond "%{HTTPS}" =on
RewriteRule "." "-" [E=protocol:https]

RewriteRule "^/mirror/foo/(.*)" "%{ENV:protocol}://backend.example.com/$1" [P]
ProxyPassReverse  "/mirror/foo/" "http://backend.example.com/"
ProxyPassReverse  "/mirror/foo/" "https://backend.example.com/"

Directive ProxyPassInherit

Description: | Héritage des directives ProxyPass définies au niveau du serveur principal
Syntaxe: | ProxyPassInherit On|Off
Défaut: | ProxyPassInherit On
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache.

Cette directive permet à un serveur virtuel d'hériter des directives ProxyPass définies au niveau du serveur principal. Si vous utilisez la fonctionnalité de modifications dynamiques du Balancer Manager, cette directive peut causer des problèmes et des comportements inattendus et doit donc être désactivée.

Les valeurs définies au niveau du serveur principal constituent les valeurs par défaut pour tous les serveurs virtuels.

La désactivation de ProxyPassInherit désactive aussi la directive BalancerInherit.

Directive ProxyPassInterpolateEnv

Description: | Active l'interpolation des variables d'environnement dans les configurations de mandataires inverses
Syntaxe: | ProxyPassInterpolateEnv On|Off
Défaut: | ProxyPassInterpolateEnv Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Disponible depuis la version 2.2.9 d'Apache

Cette directive, ainsi que l'argument interpolate des directives ProxyPass, ProxyPassReverse, ProxyPassReverseCookieDomain et ProxyPassReverseCookiePath, permet de configurer dynamiquement un mandataire inverse à l'aide de variables d'environnement, ces dernières pouvant être définies par un autre module comme mod_rewrite. Elle affecte les directives ProxyPass, ProxyPassReverse, ProxyPassReverseCookieDomain, et ProxyPassReverseCookiePath, en leur indiquant de remplacer la chaîne ${nom_var} dans les directives de configuration par la valeur de la variable d'environnement nom_var (si l'option interpolate est spécifiée).

Conservez cette directive à off (pour les performances du serveur), sauf si vous en avez réellement besoin.

Directive ProxyPassMatch

Description: | Fait correspondre des serveurs distants dans l'espace d'URL du serveur local en utilisant des expressions rationnelles
Syntaxe: | ProxyPassMatch [regex] !|url [clé=valeur [clé=valeur ...]]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy

Cette directive est identique à la directive ProxyPass, mais fait usage des expressions rationnelles, au lieu d'une simple comparaison de préfixes. L'expression rationnelle spécifiée est comparée à l'url, et si elle correspond, le serveur va substituer toute correspondance entre parenthèses dans la chaîne donnée et l'utiliser comme nouvelle url.

Note : Cette directive ne peut pas être utilisée dans un contexte de niveau répertoire.

Supposons que le serveur local a pour adresse http://example.com/ ; alors

ProxyPassMatch "^(/.*\.gif)$" "http://backend.example.com/$1"

va provoquer la conversion interne de la requête locale http://example.com/foo/bar.gif en une requête mandatée pour http://backend.example.com/foo/bar.gif.

Note

L'argument URL doit pouvoir être interprété en tant qu'URL avant les substitutions d'expressions rationnelles (et doit aussi l'être après). Ceci limite les correspondances que vous pouvez utiliser. Par exemple, si l'on avait utilisé

        ProxyPassMatch "^(/.*\.gif)$"
    "http://backend.example.com:8000$1"

dans l'exemple précédent, nous aurions provoqué une erreur de syntaxe au démarrage du serveur. C'est une bogue (PR 46665 dans ASF bugzilla), et il est possible de la contourner en reformulant la correspondance :

ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com:8000/$1"

Le drapeau ! vous permet de ne pas mandater un sous-répertoire donné.

Dans une section <LocationMatch>, le premier argument est omis et l'expression rationnelle est obtenue à partir de la directive <LocationMatch>.

Si vous avez besoin d'une configuration du mandataire inverse plus flexible, voyez la directive RewriteRule avec le drapeau [P].

Substitution par défaut

Lorsque le paramètre URL n'utilise pas de références arrières dans l'expression rationnelle, l'URL originale sera ajoutée au paramètre URL.

Avertissement à propos de la sécurité

Lors de la construction de l'URL cible de la règle, il convient de prendre en compte l'impact en matière de sécurité qu'aura le fait de permettre au client d'influencer le jeu d'URLs pour lesquelles votre serveur agira en tant que mandataire. Assurez-vous que la partie protocole://nom-serveur de l'URL soit fixe, ou ne permette pas au client de l'influencer induement.

Directive ProxyPassReverse

Description: | Ajuste l'URL dans les en-têtes de la réponse HTTP envoyée par un serveur mandaté en inverse
Syntaxe: | ProxyPassReverse [chemin] url [interpolate]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy

Cette directive permet de faire en sorte qu'Apache httpd ajuste l'URL dans les en-têtes Location, Content-Location et URI des réponses de redirection HTTP. Ceci est essentiel lorsqu'Apache httpd est utilisé en tant que mandataire inverse (ou passerelle), afin d'éviter de court-circuiter le mandataire inverse suite aux redirections HTTP sur le serveur d'arrière-plan qui restent derrière le mandataire inverse.

Seuls les en-têtes de réponse HTTP spécialement mentionnés ci-dessus seront réécrits. Apache httpd ne réécrira ni les autres en-têtes de réponse, ni par défaut les références d'URLs dans les pages HTML. Cela signifie que dans le cas où un contenu mandaté contient des références à des URLs absolues, elles court-circuiteront le mandataire. Pour réécrire un contenu HTML afin qu'il corresponde au mandataire, vous devez charger et activer le module mod_proxy_html.

chemin est le nom d'un chemin virtuel local. url est une URL partielle pour le serveur distant. Ces paramètres s'utilisent de la même façon qu'avec la directive ProxyPass.

Supposons par exemple que le serveur local a pour adresse http://example.com/ ; alors

ProxyPass         "/mirror/foo/" "http://backend.example.com/"
ProxyPassReverse  "/mirror/foo/" "http://backend.example.com/"
ProxyPassReverseCookieDomain  "backend.example.com" "public.example.com"
ProxyPassReverseCookiePath  "/"  "/mirror/foo/"

ne va pas seulement provoquer la conversion interne d'une requête locale pour http://example.com/miroir/foo/bar en une requête mandatée pour http://backend.example.com/bar (la fonctionnalité fournie par ProxyPass). Il va aussi s'occuper des redirections que le serveur backend.example.com envoie lorsqu'il redirige http://backend.example.com/bar vers http://backend.example.com/quux. Apache httpd corrige ceci en http://example.com/miroir/foo/quux avant de faire suivre la redirection HTTP au client. Notez que le nom d'hôte utilisé pour construire l'URL est choisi en respectant la définition de la directive UseCanonicalName.

Notez que la directive ProxyPassReverse peut aussi être utilisée en conjonction avec la fonctionnalité de mandataire (RewriteRule ... [P]) du module mod_rewrite, car elle ne dépend pas d'une directive ProxyPass correspondante.

Le mot-clé optionnel interpolate, en combinaison avec la directive ProxyPassInterpolateEnv, permet l'interpolation des variables d'environnement spécifiées en utilisant le format ${VARNAME} Notez que l'interpolation n'est pas supportée dans la partie protocole d'une URL.

Lorsque cette directive est utilisée dans une section <Location>, le premier argument est omis et le répertoire local est obtenu à partir de l'argument de la directive <Location>. Il en est de même à l'intérieur d'une section <LocationMatch>, mais le résultat ne sera probablement pas celui attendu car ProxyPassReverse va interpréter l'expression rationnelle littéralement comme un chemin ; si besoin est dans ce cas, définissez la directive ProxyPassReverse en dehors de la section, ou dans une section <Location> séparée.

Cette directive ne peut pas être placée dans une section <Directory> ou <Files>.

Directive ProxyPassReverseCookieDomain

Description: | Ajuste la chaîne correspondant au domaine dans les en-têtes Set-Cookie en provenance d'un serveur mandaté
Syntaxe: | ProxyPassReverseCookieDomain domaine-interne domaine-public [interpolate]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy

L'utilisation de cette directive est similaire à celle de la directive ProxyPassReverse, mais au lieu de réécrire des en-têtes qui contiennent des URLs, elle réécrit la chaîne correspondant au domaine dans les en-têtes Set-Cookie.

Directive ProxyPassReverseCookiePath

Description: | Ajuste la chaîne correspondant au chemin dans les en-têtes Set-Cookie en provenance d'un serveur mandaté
Syntaxe: | ProxyPassReverseCookiePath chemin-interne chemin-public [interpolate]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy

Cette directive s'avère utile en conjonction avec la directive ProxyPassReverse dans les situations où les chemins d'URL d'arrière-plan correspondent à des chemins publics sur le mandataire inverse. Cette directive permet de réécrire la chaîne path dans les en-têtes Set-Cookie. Si le début du chemin du cookie correspond à chemin-interne, le chemin du cookie sera remplacé par chemin-public.

Dans l'exemple fourni avec la directive ProxyPassReverse, la directive :

ProxyPassReverseCookiePath  "/"  "/mirror/foo/"

va réécrire un cookie possédant un chemin d'arrière-plan / (ou /example ou en fait tout chemin) en /mirror/foo/..

Directive ProxyPreserveHost

Description: | Utilise l'en-tête de requête entrante Host pour la requête du mandataire
Syntaxe: | ProxyPreserveHost On|Off
Défaut: | ProxyPreserveHost Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Utilisable dans un contexte de répertoire depuis la version 2.3.3.

Lorsqu'elle est activée, cette directive va transmettre l'en-tête Host: de la requête entrante vers le serveur mandaté, au lieu du nom d'hôte spécifié par la directive ProxyPass.

Cette directive est habituellement définie à Off. Elle est principalement utile dans les configurations particulières comme l'hébergement virtuel mandaté en masse à base de nom, où l'en-tête Host d'origine doit être évalué par le serveur d'arrière-plan.

Directive ProxyReceiveBufferSize

Description: | Taille du tampon réseau pour les connexions mandatées HTTP et FTP
Syntaxe: | ProxyReceiveBufferSize octets
Défaut: | ProxyReceiveBufferSize 0
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

La directive ProxyReceiveBufferSize permet de spécifier une taille de tampon réseau explicite (TCP/IP) pour les connexions mandatées HTTP et FTP, afin d'améliorer le débit de données. Elle doit être supérieure à 512 ou définie à 0 pour indiquer que la taille de tampon par défaut du système doit être utilisée.

Exemple

ProxyReceiveBufferSize 2048

Directive ProxyRemote

Description: | Mandataire distant à utiliser pour traiter certaines requêtes
Syntaxe: | ProxyRemote comparaison serveur-distant
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

Cette directive permet de définir des mandataires distants pour ce mandataire. comparaison est soit le nom d'un protocole que supporte le serveur distant, soit une URL partielle pour laquelle le serveur distant devra être utilisé, soit * pour indiquer que le serveur distant doit être utilisé pour toutes les requêtes. serveur-distant est une URL partielle correspondant au serveur distant. Syntaxe :

serveur-distant = protocole://nom-serveur[:port]

protocole est effectivement le protocole à utiliser pour communiquer avec le serveur distant ; ce module ne supporte que http et https. Lorsqu'on utilise https, les requêtes sont redirigées par le mandataire distant en utilisant la méthode HTTP CONNECT.

Exemple

ProxyRemote "http://goodguys.example.com/"
"http://mirrorguys.example.com:8000"
ProxyRemote "*" "http://cleverproxy.localdomain"
ProxyRemote "ftp" "http://ftpproxy.mydomain:8080"

Dans la dernière ligne de l'exemple, le mandataire va faire suivre les requêtes FTP, encapsulées dans une autre requête mandatée HTTP, vers un autre mandataire capable de les traiter.

Cette directive supporte aussi les configurations de mandataire inverse ; un serveur web d'arrière-plan peut être intégré dans l'espace d'URL d'un serveur virtuel, même si ce serveur est caché par un autre mandataire direct.

Directive ProxyRemoteMatch

Description: | Le mandataire distant à utiliser pour traiter les requêtes correspondant à une expression rationnelle
Syntaxe: | ProxyRemoteMatch regex serveur-distant
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

La directive ProxyRemoteMatch est identique à la directive ProxyRemote, à l'exception du premier argument qui est une expression rationnelle à mettre en correspondance avec l'URL de la requête.

Directive ProxyRequests

Description: | Active la fonctionnalité (standard) de mandataire direct
Syntaxe: | ProxyRequests On|Off
Défaut: | ProxyRequests Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

Cette directive permet d'activer/désactiver la fonctionnalité de serveur mandataire direct d'Apache httpd. Définir ProxyRequests à Off n'interdit pas l'utilisation de la directive ProxyPass.

Pour une configuration typique de mandataire inverse ou passerelle, cette directive doit être définie à Off.

Afin d'activer la fonctionnalité de mandataire pour des sites HTTP et/ou FTP, les modules mod_proxy_http et/ou mod_proxy_ftp doivent également être chargés dans le serveur.

Pour activer la fonctionnalité de mandataire sur les sites chiffrés en HTTPS, le module mod_proxy_connect doit également être chargé dans le serveur.

Avertissement

N'activez pas la fonctionnalité de mandataire avec la directive ProxyRequests avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Voir aussi

  • Mandataires/Passerelles directs et inverses

Directive ProxySet

Description: | Définit différents paramètres relatifs à la répartition de charge des mandataires et aux membres des groupes de répartition de charge
Syntaxe: | ProxySet url clé=valeur [clé=valeur ...]
Contexte: | répertoire
Statut: | Extension
Module: | mod_proxy
Compatibilité: | ProxySet n'est disponible que depuis la version 2.2 du serveur HTTP Apache.

Cette directive propose une méthode alternative pour définir tout paramètre relatif aux répartiteurs de charge et serveurs cibles de mandataires normalement définis via la directive ProxyPass. Si elle se trouve dans un conteneur <Proxy url de répartiteur|url de serveur cible>, l'argument url n'est pas nécessaire. Comme effet de bord, le répartiteur ou serveur cible respectif est créé. Ceci peut s'avérer utile pour la mise en oeuvre d'un mandataire inverse via une directive RewriteRule au lieu de ProxyPass.

<Proxy "balancer://hotcluster">
    BalancerMember "http://www2.example.com:8080" loadfactor=1
    BalancerMember "http://www3.example.com:8080" loadfactor=2
    ProxySet lbmethod=bytraffic
</Proxy>
<Proxy "http://backend">
    ProxySet keepalive=On
</Proxy>
ProxySet "balancer://foo" lbmethod=bytraffic timeout=15
ProxySet "ajp://backend:7001" timeout=15

Avertissement

Gardez à l'esprit qu'une même clé de paramètre peut avoir différentes significations selon qu'elle s'applique à un répartiteur ou à un serveur cible, et ceci est illustré par les deux exemples précédents où il est question d'un timeout.

Directive ProxySourceAddress

Description: | Définit l'adresse IP locale pour les connexions mandatées sortantes
Syntaxe: | ProxySourceAddress adresse
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Disponible depuis la version 2.3.9

Cette directive permet de définir une adresse IP locale spécifique à laquelle faire référence lors d'une connexion à un serveur d'arrière-plan.

Directive ProxyStatus

Description: | Affiche l'état du répartiteur de charge du mandataire dans mod_status
Syntaxe: | ProxyStatus Off|On|Full
Défaut: | ProxyStatus Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy
Compatibilité: | Disponible depuis la version 2.2 d'Apache

Cette directive permet de spécifier si les données d'état du répartiteur de charge du mandataire doivent être affichées via la page d'état du serveur du module mod_status.

Note

L'argument Full produit le même effet que l'argument On.

Directive ProxyTimeout

Description: | Délai d'attente réseau pour les requêtes mandatées
Syntaxe: | ProxyTimeout secondes
Défaut: | Valeur de la directive Timeout
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

Cette directive permet à l'utilisateur de spécifier un délai pour les requêtes mandatées. Ceci s'avère utile dans le cas d'un serveur d'applications lent et bogué qui a tendance à se bloquer, et si vous préférez simplement renvoyer une erreur timeout et abandonner la connexion en douceur plutôt que d'attendre jusqu'à ce que le serveur veuille bien répondre.

Directive ProxyVia

Description: | Information fournie dans l'en-tête de réponse HTTP Via pour les requêtes mandatées
Syntaxe: | ProxyVia On|Off|Full|Block
Défaut: | ProxyVia Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy

Cette directive permet de contrôler l'utilisation de l'en-tête HTTP Via: par le mandataire. Le but recherché est de contrôler le flux des requêtes mandatées tout au long d'une chaîne de serveurs mandataires. Voir RFC 2616 (HTTP/1.1), section 14.45 pour une description des lignes d'en-tête Via:.

  • Si elle est définie à Off, valeur par défaut, cette directive n'effectue aucun traitement particulier. Si une requête ou une réponse contient un en-tête Via:, il est transmis sans modification.
  • Si elle est définie à On, chaque requête ou réponse se verra ajouter une ligne d'en-tête Via: pour le serveur courant.
  • Si elle est définie à Full, chaque ligne d'en-tête Via: se verra ajouter la version du serveur Apache httpd sous la forme d'un champ de commentaire Via:.
  • Si elle est définie à Block, chaque requête mandatée verra ses lignes d'en-tête Via: supprimées. Aucun nouvel en-tête Via: ne sera généré.


mod_proxy_ajp - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_ajp

Description: | Module de support AJP pour mod_proxy
Statut: | Extension
Identificateur de Module: | proxy_ajp_module
Fichier Source: | mod_proxy_ajp.c
Compatibilité: | Disponible depuis la version 2.1 d'Apache

Sommaire

Ce module nécessite le chargement de mod_proxy. Il fournit le support du Protocole Apache JServ version 1.3 (nommé dans la suite de ce document AJP13).

Pour être en mesure d'exploiter le protocole AJP13, il est donc nécessaire de charger les modules mod_proxy et mod_proxy_ajp.

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • Documentation sur les variables d'environnement

Utilisation

Ce module permet de mandater en inverse un serveur d'application d'arrière-plan (comme Apache Tomcat) qui utilise le protocole AJP13. Son utilisation est similaire à celle d'un mandataire inverse HTTP, mais s'appuie sur le prefixe ajp:// :

Mandataire inverse simple

ProxyPass "/app" "ajp://backend.example.com:8009/app"

On peut aussi configurer un répartiteur de charge :

Mandataire inverse avec répartiteur de charge

<Proxy balancer://cluster>
    BalancerMember "ajp://app1.example.com:8009" loadfactor=1
    BalancerMember "ajp://app2.example.com:8009" loadfactor=2
    ProxySet lbmethod=bytraffic
</Proxy>
ProxyPass "/app" "balancer://cluster/app"

Notez qu'en général, la directive ProxyPassReverse n'est pas nécessaire. La requête AJP inclut l'en-tête host original fourni au mandataire, et le serveur d'application est sensé générer des en-têtes auto-référençants relatifs à cet hôte ; aucune réécriture n'est donc nécessaire.

La situation la plus courante dans laquelle la directive ProxyPassReverse est nécessaire se rencontre lorsque le chemin de l'URL au niveau du mandataire est différente de celle du serveur d'arrière-plan. Dans ce cas, un en-tête redirect peut être réécrit relativement à l'URL de l'hôte original (et non du serveur d'arrière-plan ajp:// URL) ; par exemple :

Réécriture d'un chemin mandaté

ProxyPass "/apps/foo" "ajp://backend.example.com:8009/foo"
ProxyPassReverse "/apps/foo" "http://www.example.com/foo"

Il est cependant préférable en général de déployer l'application sur le serveur d'arrière-plan avec le même chemin que sur le mandataire.

Variables d'environnement

Les variables d'environnement dont le nom possède le préfixe AJP_ sont transmises au serveur original en tant qu'attributs de requête AJP (le préfixe AJP_ étant supprimé du nom de la clé).

Vue d'ensemble du protocole

Le protocole AJP13 est orienté paquet. Le format binaire a été préféré, probablement pour des raisons de performances, au format texte pourtant plus lisible. Le serveur web communique avec le conteneur de servlets sur une connexion TCP. Pour diminuer la charge induite par le processus de création de socket, le serveur web va tenter d'utiliser des connexions TCP persistantes avec le conteneur de servlets, et de réutiliser les connexions pendant plusieurs cycles requêtes/réponse.

Lorsqu'une connexion a été assignée à une requête particulière, elle ne sera utilisée pour aucune autre jusqu'à ce que le cycle de traitement de la requête se soit terminé. En d'autres termes, il n'y a pas de multiplexage des requêtes sur une connexion. Ceci se traduit par un code beaucoup plus simple à chaque extrémité de la connexion, un nombre plus important de connexions étant cependant ouvertes en même temps.

Lorsque le serveur web a ouvert une connexion vers le conteneur de servlets, celle-ci peut se trouver dans l'un des états suivants :

  • Idle
    Aucune requête n'est traitée sur cette connexion.
  • Assigned
    La connexion fait l'objet d'un traitement de requête.

Lorsqu'une connexion est assignée au traitement d'une requête particulière, les informations de base de cette dernière (comme les en-têtes HTTP, etc...) sont envoyées sur la connexion sous une forme très condensée (par exemple les chaînes courantes sont codées sous forme d'entiers). Vous trouverez des détails sur ce format plus loin dans la structure des paquets de requête. Si la requête possède un corps (content-length > 0), il est envoyé dans un paquet séparé immédiatement après.

A ce moment, le conteneur est probablement prêt à traiter la requête. Au cours de ce traitement, il peut renvoyer les messages suivants au serveur web :

  • SEND_HEADERS
    Renvoie un jeu d'en-têtes au navigateur.
  • SEND_BODY_CHUNK
    Renvoie un tronçon de corps de requête au navigateur.
  • GET_BODY_CHUNK
    Reçoit un autre tronçon de données de la requête si elle n'a pas encore été transmise intégralement. Ce type de transmission est nécessaire car les paquets possèdent une taille maximale fixe, et des quantités quelconques de données peuvent être contenues dans le corps de la requête (pour un chargement de fichier, par exemple). Notez que cela n'a rien à voir avec le transfert HTTP fractionné.
  • END_RESPONSE
    Termine le cycle du traitement de la requête.

Chaque message est associé à un paquet de données formaté différemment. Voir plus loin les structures des paquets de réponses pour plus de détails.

Structure de base des paquets

Ce protocole hérite en partie de XDR, mais il diffère sur de nombreux points (pas d'alignement sur 4 bits, par exemple).

AJP13 utilise les octets selon leur ordre d'arrivée par le réseau pour tous les types de données.

Le protocole comporte quatre types de données : octets, booléens, entiers et chaînes de caractères.

Octet
Un seul octet.
Booléen
Un seul octet, 1 = vrai, 0 = faux. L'utilisation d'autres valeurs non nulles (dans le style C) peut fonctionner dans certains cas, mais pas dans certains autres..
Entier
Un nombre compris entre 0 et 2^16 (32768), stocké sur 2 octets en débutant par l'octet de poids forts.
Chaîne
Une chaîne de taille variable (longueur limitée à 2^16). Elle est codée comme suit : les deux premiers octets représentent la longueur de la chaîne, les octets suivants constituent la chaîne proprement dite (y compris le '\0' final). Notez que la longueur encodée dans les deux premiers octets ne prend pas en compte le '\0' final, de la même manière que strlen. Cela peut prêter à confusion du point de vue de Java qui est surchargé de déclarations d'autoincrémentation étranges destinées à traiter ces terminateurs. Je suppose que le but dans lequel cela a été conçu ainsi était de permettre au code C d'être plus efficace lors de la lecture de chaînes en provenance du conteneur de servlets -- avec le caractère \0 final, le code C peut transmettre des références dans un seul tampon, sans avoir à effectuer de copie. En l'absence du caractère \0 final, le code C doit effectuer une copie afin de pouvoir tenir compte de sa notion de chaîne.

Taille du paquet

Selon la majorité du code, la taille maximale du paquet est de 8 * 1024 bytes (8K). La taille réelle du paquet est encodée dans l'en-tête.

En-têtes de paquet

Les paquets envoyés par le serveur vers le conteneur commencent par 0x1234. Les paquets envoyés par le conteneur vers le serveur commencent par AB (c'est à dire le code ASCII de A suivi du code ASCII de B). Ensuite, vient un entier (codé comme ci-dessus) représentant la longueur des données transmises. Bien que ceci puisse faire croire que la taille maximale des données est de 2^16, le code définit en fait ce maximum à 8K.

Format du paquet (Serveur->Conteneur)
Octet | 0 | 1 | 2 | 3 | 4...(n+3)
Contenu | 0x12 | 0x34 | Taille des données (n) |  | Data
Format du paquet (Conteneur->Serveur)
Octet | 0 | 1 | 2 | 3 | 4...(n+3)
Contenu | A | B | Taille des données (n) |  | Data

Pour la plupart des paquets, le premier octet de la charge utile encode le type de message, à l'exception des paquets contenant un corps de requête envoyés du serveur vers le conteneur -- ils comportent un en-tête standard (0x1234 suivi de la taille du paquet), mais celui-ci n'est suivi d'aucun préfixe.

Le serveur web peut envoyer les messages suivants au conteneur de servlets :

Code | Type de paquet | Signification
2 | Fait suivre la requête | Débute le cycle de traitement de la requête avec les données qui suivent.
7 | Arrêt | Le serveur web demande au conteneur de s'arrêter.
8 | Ping | Le serveur web demande au conteneur de prendre le contrôle (phase de connexion sécurisée).
10 | CPing | Le serveur web demande au conteneur de répondre rapidement avec un CPong.
none | Données | Taille (2 octets) et les données correspondantes.

À des fins de sécurité, le conteneur n'effectuera réellement son Arrêt que si la demande provient de la machine par laquelle il est hébergé.

Le premier paquet Données est envoyé immédiatement après le paquet Faire suivre la requête par le serveur web.

Le conteneur de servlets peut envoyer les types de messages suivants au serveur web :

Code | Type de paquet | Signification
3 | Envoi d'un tronçon de corps | Envoi d'un tronçon de corps depuis le conteneur de servlets vers le serveur web (et probablement vers le navigateur).
4 | Envoie les en-têtes | Envoi des en-têtes de réponse depuis le conteneur de servlets vers le serveur web (et probablement vers le navigateur).
5 | Fin de la réponse | Marque la fin de la réponse (et par conséquent du cycle de traitement de la requête).
6 | Réception du tronçon de corps suivant | Réception de la suite des données de la requête si elles n'ont pas encore été entièrement transmises.
9 | Réponse CPong | La réponse à une requête CPing

Chacun des messages ci-dessus possède une structure interne différente dont vous trouverez les détails ci-dessous.

Structure des paquets de requête

Pour les messages de type Faire suivre la requête depuis le serveur vers le conteneur :

AJP13_FORWARD_REQUEST :=
    prefix_code      (byte) 0x02 = JK_AJP13_FORWARD_REQUEST
    method           (byte)
    protocol         (string)
    req_uri          (string)
    remote_addr      (string)
    remote_host      (string)
    server_name      (string)
    server_port      (integer)
    is_ssl           (boolean)
    num_headers      (integer)
    request_headers *(req_header_name req_header_value)
    attributes      *(attribut_name attribute_value)
    request_terminator (byte) OxFF

Les request_headers possèdent la structure suivante :

req_header_name :=
    sc_req_header_name | (string)  [voir ci-dessous pour la manière dont
    ceci est interprété]

sc_req_header_name := 0xA0xx (integer)

req_header_value := (string)

Les attributes sont optionnels et possèdent la structure suivante :

attribute_name := sc_a_name | (sc_a_req_attribute string)

attribute_value := (string)

Un des en-têtes les plus importants est content-length, car il indique si le conteneur doit ou non attendre un autre paquet immédiatement.

Description détaillée de la requête que le serveur fait suivre vers le conteneur

Préfixe de la requête

Pour toutes les requêtes, ce préfixe est 2. Voir ci-dessus pour les détails des autres codes de préfixes.

Méthode

La méthode HTTP, encodée sous la forme d'un seul octet :

Nom commande | Code
OPTIONS | 1
GET | 2
HEAD | 3
POST | 4
PUT | 5
DELETE | 6
TRACE | 7
PROPFIND | 8
PROPPATCH | 9
MKCOL | 10
COPY | 11
MOVE | 12
LOCK | 13
UNLOCK | 14
ACL | 15
REPORT | 16
VERSION-CONTROL | 17
CHECKIN | 18
CHECKOUT | 19
UNCHECKOUT | 20
SEARCH | 21
MKWORKSPACE | 22
UPDATE | 23
LABEL | 24
MERGE | 25
BASELINE_CONTROL | 26
MKACTIVITY | 27

Les versions futures d'ajp13 pourront transmettre des méthodes supplémentaires, même si elles ne font pas partie de cette liste.

protocol, req_uri, remote_addr, remote_host, server_name, server_port, is_ssl

Les significations de ces éléments sont triviales. Ils sont tous obligatoires et seront envoyés avec chaque requête.

En-têtes

La structure de request_headers est la suivante : tout d'abord, le nombre d'en-têtes num_headers est encodé, suivi d'une liste de paires nom d'en-tête req_header_name / valeur req_header_value. Les noms d'en-têtes courants sont codés sous forme d'entiers afin de gagner de la place. Si le nom d'en-tête ne fait partie de la liste des en-têtes courants, il est encodé normalement (une chaîne de caractères préfixée par la taille). La liste des en-têtes courants sc_req_header_name avec leurs codes se présente comme suit (il sont tous sensibles à la casse) :

Nom | Valeur du code | Nom du code
accept | 0xA001 | SC_REQ_ACCEPT
accept-charset | 0xA002 | SC_REQ_ACCEPT_CHARSET
accept-encoding | 0xA003 | SC_REQ_ACCEPT_ENCODING
accept-language | 0xA004 | SC_REQ_ACCEPT_LANGUAGE
authorization | 0xA005 | SC_REQ_AUTHORIZATION
connection | 0xA006 | SC_REQ_CONNECTION
content-type | 0xA007 | SC_REQ_CONTENT_TYPE
content-length | 0xA008 | SC_REQ_CONTENT_LENGTH
cookie | 0xA009 | SC_REQ_COOKIE
cookie2 | 0xA00A | SC_REQ_COOKIE2
host | 0xA00B | SC_REQ_HOST
pragma | 0xA00C | SC_REQ_PRAGMA
referer | 0xA00D | SC_REQ_REFERER
user-agent | 0xA00E | SC_REQ_USER_AGENT

Le code Java qui lit ceci extrait l'entier représenté par les deux premiers octets, et si le premier octet est '0xA0', il utilise l'entier représenté par le deuxième octet comme index d'un tableau de noms d'en-têtes. Si le premier octet n'est pas 0xA0, l'entier représenté par les deux octets est considéré comme la longueur d'une chaîne qui est alors lue.

Ceci ne peut fonctionner que si aucun nom d'en-tête ne possède une taille supérieure à 0x9FFF (==0xA000 - 1), ce qui est vraisemblable, bien qu'un peu arbitraire.

Note:

L'en-tête content-length est extrêmement important. S'il est présent et non nul, le conteneur considère que la requête possède un corps (une requête POST, par exemple), et lit immédiatement le paquet suivant dans le flux d'entrée pour extraire ce corps.

Attributs

Les attributs préfixés par ? (par exemple ?context) sont tous optionnels. Chacun d'eux est représenté par un octet correspondant au type de l'attribut et par sa valeur (chaîne ou entier). Ils peuvent être envoyés dans un ordre quelconque (bien que le code C les envoie dans l'ordre ci-dessous). Un code de terminaison spécial est envoyé pour signaler la fin de la liste des attributs optionnels. La liste des codes est la suivante :

Information | Valeur code | Type de valeur | Note
?context | 0x01 | - | Non implémenté actuellement
?servlet_path | 0x02 | - | Non implémenté actuellement
?remote_user | 0x03 | String |
?auth_type | 0x04 | String |
?query_string | 0x05 | String |
?jvm_route | 0x06 | String |
?ssl_cert | 0x07 | String |
?ssl_cipher | 0x08 | String |
?ssl_session | 0x09 | String |
?req_attribute | 0x0A | String | Nom (le nom de l'attribut vient ensuite)
?ssl_key_size | 0x0B | Integer |
are_done | 0xFF | - | request_terminator

context et servlet_path ne sont pas définis actuellement par le code C, et la majorité du code Java ignore complètement ce qui est envoyé par l'intermédiaire de ces champs (il va même parfois s'interrompre si une chaîne est envoyée après un de ces codes). Je ne sais pas si c'est une bogue ou une fonctionnalité non implémentée, ou tout simplement du code obsolète, mais en tout cas, il n'est pris en charge par aucune des deux extrémités de la connexion.

remote_user et auth_type concernent probablement l'authentification au niveau HTTP, et contiennent le nom de l'utilisateur distant ainsi que le type d'authentification utilisée pour établir son identité (à savoir Basic, Digest).

query_string, ssl_cert, ssl_cipher et ssl_session contiennent les éléments HTTP et HTTPS correspondants.

jvm_route est utilisé dans le cadre des sessions persistantes, en associant une session utilisateur à une instance Tomcat particulière en présence de plusieurs répartiteurs de charge.

Au delà de cette liste de base, tout autre attribut supplémentaire peut être envoyé via le code req_attribute 0x0A. Une paire de chaînes représentant le nom et la valeur de l'attribut est envoyée immédiatement après chaque instance de ce code. Les variables d'environnement sont transmises par cette méthode.

Enfin, lorsque tous les attributs ont été transmis, le terminateur d'attributs, 0xFF, est envoyé. Ce dernier indique à la fois la fin de la liste d'attributs et la fin du paquet de la requête

Structure du paquet de la réponse

Pour les messages que le conteneur peut renvoyer au serveur.

AJP13_SEND_BODY_CHUNK :=
  prefix_code   3
  chunk_length  (integer)
  chunk        *(byte)
  chunk_terminator (byte) Ox00

AJP13_SEND_HEADERS :=
  prefix_code       4
  http_status_code  (integer)
  http_status_msg   (string)
  num_headers       (integer)
  response_headers *(res_header_name header_value)

res_header_name :=
    sc_res_header_name | (string)   [voir ci-dessous pour la manière
    dont ceci est interprété]

sc_res_header_name := 0xA0 (byte)

header_value := (string)

AJP13_END_RESPONSE :=
  prefix_code       5
  reuse             (boolean)

AJP13_GET_BODY_CHUNK :=
  prefix_code       6
  requested_length  (integer)

Détails:

Envoi d'un tronçon de corps

Le tronçon se compose essentiellement de données binaires et est renvoyé directement au navigateur.

Envoi des en-têtes

Les code et message d'état correspondent aux code et message HTTP habituels (par exemple 200 et OK). Les noms d'en-têtes de réponses sont codés de la même façon que les noms d'en-têtes de requêtes. Voir ci-dessus le codage des en-têtes pour plus de détails à propos de la manière dont les codes se distinguent des chaînes.
Les codes des en-têtes courants sont ::

Nom | Valeur code
Content-Type | 0xA001
Content-Language | 0xA002
Content-Length | 0xA003
Date | 0xA004
Last-Modified | 0xA005
Location | 0xA006
Set-Cookie | 0xA007
Set-Cookie2 | 0xA008
Servlet-Engine | 0xA009
Status | 0xA00A
WWW-Authenticate | 0xA00B

La valeur de l'en-tête est codée immédiatement après le code ou la chaîne du nom d'en-tête.

Fin de la réponse

Signale la fin de ce cycle de traitement de requête. Si le drapeau reuse est à true (toute valeur autre que 0 en langage C pur), cette connexion TCP peut être réutilisée pour traiter de nouvelles requêtes entrantes. Si reuse est à false (==0), la connexion sera fermée.

Réception d'un tronçon de corps

Le conteneur réclame la suite des données de la requête (dans le cas où la taille du corps était trop importante pour pouvoir être contenue dans le premier paquet envoyé, où lorsque la requête est fractionnée). Le serveur va alors envoyer un paquet contenant une quantité de données correspondant au minimum de la request_length, la taille maximale de corps envoyée (8186 (8 Koctets - 6)), et le nombre réel d'octets restants à envoyer pour ce corps de requête.
S'il ne reste plus de données à transmettre pour ce corps de requête (c'est à dire si le conteneur de servlets tente de lire au delà de la fin du corps), le serveur va renvoyer un paquet vide dont la charge utile est de longueur 0 et se présentant sous la forme (0x12,0x34,0x00,0x00).


mod_proxy_balancer - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_balancer

Description: | Extension de mod_proxy pour le support de la répartition de charge
Statut: | Extension
Identificateur de Module: | proxy_balancer_module
Fichier Source: | mod_proxy_balancer.c
Compatibilité: | Disponible depuis la version 2.1 d'Apache

Sommaire

Pour pouvoir fonctionner, ce module requiert le chargement de mod_proxy, et il fournit le support de la répartition de charge pour tous les protocoles supportés. Parmi ces protocoles, les plus importants sont :

  • HTTP, avec le module mod_proxy_http
  • FTP, avec le module mod_proxy_ftp
  • AJP13, avec le module mod_proxy_ajp
  • WebSocket, avec le module mod_proxy_wstunnel

L'algorithme de planification de la répartition de charge n'est pas fourni par ce module, mais par ceux-ci :

  • mod_lbmethod_byrequests
  • mod_lbmethod_bytraffic
  • mod_lbmethod_bybusyness
  • mod_lbmethod_heartbeat

Ainsi, pour mettre en oeuvre la répartition de charge, mod_proxy, mod_proxy_balancer et au moins un des modules fournissant l'algorithme de planification de la répartition de charge doivent être chargés dans le serveur.

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • BalancerMember
  • BalancerGrowth
  • BalancerPersist
  • BalancerInherit

L'algorithme de planification de la répartition de charge

A l'heure actuelle, 3 algorithmes de planification de la répartition de charge sont disponibles : ils se basent respectivement sur le comptage des requêtes, la mesure du trafic et le comptage des requêtes en attente. Ils sont contrôlés par la valeur de lbmethod dans la définition du répartiteur. Voir la directive ProxyPass pour plus de détails, et en particulier la configuration du répartiteur et de ses membres.

Répartition de charge avec abonnement utilisateur (stickyness)

Le répartiteur supporte l'abonnement utilisateur. Lorsqu'une requête est mandatée vers un serveur d'arrière-plan particulier, toutes les requêtes suivantes du même utilisateur seront alors mandatées vers le même serveur d'arrière-plan. De nombreux répartiteurs de charge implémentent cette fonctionnalité via une table qui associe les adresses IP des clients aux serveurs d'arrière-plan. Cette approche est transparente aux clients et aux serveurs d'arrière-plan, mais induit certains problèmes : distribution de charge inégale si les clients se trouvent eux-mêmes derrière un mandataire, erreurs d'abonnement lorsqu'un client possède une adresse IP dynamique qui peut changer au cours d'une session et perte d'abonnement en cas de dépassement de la table de correspondances.

Le module mod_proxy_balancer implémente l'abonnement selon deux alternatives : les cookies et le codage d'URL. Le cookie peut être fourni par le serveur d'arrière-plan ou par le serveur web Apache lui-même, alors que le codage d'URL est en général effectué par le serveur d'arrière-plan.

Exemples de configuration d'un répartiteur

Avant de nous plonger dans les détails techniques, voici un exemple d'utilisation de mod_proxy_balancer mettant en oeuvre la répartition de charge entre deux serveurs d'arrière-plan :

<Proxy "balancer://mycluster">
    BalancerMember "http://192.168.1.50:80"
    BalancerMember "http://192.168.1.51:80"
</Proxy>
ProxyPass "/test" "balancer://mycluster"
ProxyPassReverse "/test" "balancer://mycluster"

Voici un autre exemple de répartiteur de charge avec abonnement utilisant mod_headers, fonctionnant même si le serveur d'arrière-plan ne définit pas de cookie de session approprié :

Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
<Proxy "balancer://mycluster">
    BalancerMember "http://192.168.1.50:80" route=1
    BalancerMember "http://192.168.1.51:80" route=2
    ProxySet stickysession=ROUTEID
</Proxy>
ProxyPass "/test" "balancer://mycluster"
ProxyPassReverse "/test" "balancer://mycluster"

Variables d'environnement exportées

A l'heure actuelle, 6 variables d'environnement sont exportées :

BALANCER_SESSION_STICKY

Cette variable se voir assignée la valeur de stickysession pour la requête courante. Il s'agit du nom du cookie ou du paramètre de requête utilisé pour les sessions avec abonnement.

BALANCER_SESSION_ROUTE

Cette variable se voit assignée la route interprétée pour la requête courante.

BALANCER_NAME

Cette variable se voit assigné le nom du répartiteur pour la requête courante. Il s'agit d'une valeur du style balancer://foo.

BALANCER_WORKER_NAME

Cette variable se voit assigné le nom du membre du groupe de répartition de charge utilisé pour la requête courante. Il s'agit d'une valeur du style http://hostA:1234.

BALANCER_WORKER_ROUTE

Cette variable se voit assignée la route du membre du groupe de répartition de charge qui sera utilisé pour la requête courante.

BALANCER_ROUTE_CHANGED

Cette variable est définie à 1 si la route de la session ne correspond pas à celle du membre du groupe de répartition de charge (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE), ou si la session ne possède pas encore de route établie. Elle peut servir à déterminer quand il est éventuellement nécessaire d'envoyer au client une route mise à jour lorsque les sessions persistantes sont utilisées.

Activation du support du gestionnaire de répartiteur

Cette fonctionnalité nécessite le chargement du module mod_status. Le gestionnaire de répartiteur permet la mise à jour dynamique des membres du groupe de répartition de charge. Vous pouvez utiliser le gestionnaire de répartiteur pour modifier le facteur de charge d'un membre particulier, ou passer ce dernier en mode hors ligne.

Ainsi, pour mettre en oeuvre la gestion du répartiteur de charge, mod_status et mod_proxy_balancer doivent être chargés dans le serveur.

Pour permettre la gestion du répartiteur de charge aux navigateurs appartenant au domaine example.com, ajoutez ces lignes à votre fichier de configuration httpd.conf :

<Location "/balancer-manager">
    SetHandler balancer-manager
    Require host example.com
</Location>

Vous pourrez alors accéder au gestionnaire du répartiteur de charge en utilisant un navigateur web pour afficher la page http://nom.de.votre.serveur/balancer-manager. Notez que pour pouvoir contrôler dynamiquement un membre de groupe de répartition, ce dernier ne doit pas être défini au sein d'une section <Location ...>.

Détails à propos de la répartition de charge par abonnement (stickyness)

Si l'abonnement s'appuie sur un cookie, vous devez définir le nom de ce cookie dont le contenu précise le serveur d'arrière-plan à utiliser. Pour ce faire, on utilise l'attribut stickysession avec la directive ProxyPass ou ProxySet. Le nom du cookie est sensible à la casse. Le répartiteur extrait le contenu du cookie et recherche un serveur membre dont la route correspond à cette valeur. La route doit aussi être définie dans la directive ProxyPass ou ProxySet. Le cookie peut être défini soit par le serveur d'arrière-plan, soit, comme indiqué dans l'exemple ci-dessus par le serveur web Apache lui-même.

Certains serveurs d'arrière-plan, tels qu'Apache Tomcat, utilisent une forme sensiblement différente de cookie d'abonnement. Tomcat ajoute le nom de l'instance Tomcat à la fin de son identifiant de session, précédé par un point. Ainsi, si le serveur web Apache trouve un point dans la valeur du cookie d'abonnement, il n'utilisera que la partie située après ce point pour rechercher sa route. Pour que Tomcat puisse connaître son nom d'instance, vous devez définir l'attribut jvmRoute dans son fichier de configuration conf/server.xml à la valeur de la route du serveur qui se connecte au Tomcat considéré. Le nom du cookie de session utilisé par Tomcat (et plus généralement par les applications web Java à base de servlets) est JSESSIONID (en majuscules), mais peut être modifié.

La seconde méthode pour implémenter l'abonnement est le codage d'URL. Ici, le serveur web recherche un paramètre dans l'URL de la requête. Le nom du paramètre est spécifié par l'attribut stickysession. Pour trouver un serveur membre, on recherche un serveur dont la route est égale à la valeur du paramètre. Comme il n'est pas aisé d'extraire et de manipuler tous les liens URL contenus dans les réponses, le travail consistant à ajouter les paramètres à chaque lien est généralement effectué par le serveur d'arrière-plan qui génère le contenu. Bien qu'il soit possible dans certains cas d'effectuer ces ajouts au niveau du serveur web via les modules mod_substitute ou mod_sed, cette méthode peut dégrader les performances.

Les standards Java implémentent le codage d'URL de manière sensiblement différente. Ils ajoutent une information de chemin à l'URL en utilisant un point-virgule (;) comme séparateur, puis ajoutent enfin l'identifiant de session. Comme dans le cas des cookies, Apache Tomcat peut insérer la valeur de l'attribut jvmRoute dans cette information de chemin. Pour qu'Apache puisse trouver ce genre d'information de chemin, vous devez définir scolonpathdelim à On dans la directive ProxyPass ou ProxySet.

Enfin, vous pouvez utiliser simultanément les cookies et le codage d'URL en définissant le nom du cookie et le nom du paramètre d'URL séparés par une barre verticale (|) comme dans l'exemple suivant :

ProxyPass "/test" "balancer://mycluster" stickysession=JSESSIONID|jsessionid scolonpathdelim=On
<Proxy "balancer://mycluster">
    BalancerMember "http://192.168.1.50:80" route=node1
    BalancerMember "http://192.168.1.51:80" route=node2
</Proxy>

Si le cookie et le paramètre de requête fournissent tous deux une information de route correcte pour la même requête, c'est l'information en provenance du paramètre de requête qui sera retenue.

Résolution des problèmes liés à la répartition de charge par abonnement

Si vous êtes confronté à des erreurs d'abonnement, comme la nécessité pour les utilisateurs de se reconnecter suite à une perte de session d'application, vous devez tout d'abord vérifier si ceci n'est pas du à une indisponibilité sporadique des serveurs d'arrière-plan ou à une erreur de configuration. La présence de messages d'erreur de type proxy dans le journal des erreurs d'Apache pourra révéler des problèmes de stabilité au niveau des serveurs d'arrière-plan.

Pour contrôler votre configuration, regardez tout d'abord si l'abonnement est à base de cookie ou de codage d'URL. L'étape suivante consiste à enregistrer certaines données dans le journal des accès en utilisant un format de journalisation personnalisé. Les champs intéressants sont les suivants :

%{MONCOOKIE}C
La valeur que contient le cookie de nom MONCOOKIE. Le nom doit correspondre au nom défini par l'attribut stickysession.
%{Set-Cookie}o
Ce champ contient tout cookie défini par le serveur d'arrière-plan. Vous pouvez ainsi vérifier si le serveur d'arrière-plan définit bien le cookie de session auquel vous vous attendez, et à quelle valeur il est défini.
%{BALANCER_SESSION_STICKY}e
Le nom du cookie ou du paramètre de requête utilisé pour la recherche de l'information de routage.
%{BALANCER_SESSION_ROUTE}e
L'information de routage extraite de la requête.
%{BALANCER_WORKER_ROUTE}e
La route du serveur choisi.
%{BALANCER_ROUTE_CHANGED}e
Contient la valeur 1 si la route extraite de la requête est différente de la route du serveur ; autrement dit, le traitement de la requête n'a pas pu être effectué dans le cadre d'une répartition de charge par abonnement.

Les pertes de session sont souvent dues à des expirations de session dont la valeur peut en général être configurée au niveau du serveur d'arrière-plan.

Si le niveau de journalisation est défini à debug ou plus, le répartiteur journalise aussi des informations détaillées à propos de l'abonnement dans le journal des erreurs, ce qui facilite la résolution des problèmes d'abonnement. Notez cependant que le volume de journalisation pourra alors s'avérer trop important pour un serveur en production sous forte charge.


mod_proxy_connect - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_connect

Description: | Extension de mod_proxy pour le traitement des requêtes CONNECT
Statut: | Extension
Identificateur de Module: | proxy_connect_module
Fichier Source: | mod_proxy_connect.c

Sommaire

Pour fonctionner, ce module nécessite le chargement de mod_proxy. Il fournit le support de la méthode HTTP CONNECT. Cette méthode est principalement utilisée pour faire franchir les serveurs mandataires aux requêtes SSL à l'aide d'un tunnel.

Ainsi, pour pouvoir traiter les requêtes CONNECT, mod_proxy et mod_proxy_connect doivent être chargés dans le serveur.

CONNECT est aussi utilisée lorsque le serveur doit envoyer une requête HTTPS via un mandataire. Dans ce cas, le serveur se comporte comme un client CONNECT. Cette fonctionnalité étant fournie par le module mod_proxy, le module mod_proxy_connect n'est dans ce cas pas nécessaire.

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Traitement des bugs

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

Voir aussi

  • mod_proxy

Informations sur les requêtes

mod_proxy_connect enregistre les informations suivantes pour journalisation via le format %{NOMVAR}n dans les directives LogFormat ou ErrorLogFormat :

proxy-source-port
Le port local utilisé pour la connexion vers le serveur d'arrière-plan.

Directive AllowCONNECT

Description: | Ports autorisés à se CONNECTer à travers le mandataire
Syntaxe: | AllowCONNECT port[-port] [port[-port]] ...
Défaut: | AllowCONNECT 443 563
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy_connect
Compatibilité: | Déplacé depuis mod_proxy à partir d'Apache 2.3.5. Plages de ports disponibles depuis Apache 2.3.7.

La directive AllowCONNECT permet de spécifier une liste de numéros ou de plages de ports auxquels la méthode de mandataire CONNECT pourra se connecter. Les navigateurs récents utilisent cette méthode dans le cas où une connexion https est requise et où le tunneling mandataire sur HTTP est en service.

Par défaut, seuls les ports par défauts https (443) et snews (563) sont pris en compte. Vous pouvez utiliser la directive AllowCONNECT pour outrepasser ces valeurs par défaut et n'autoriser les connexions que vers les ports spécifiés.


mod_proxy_express - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_express

Description: | Extension à mod_proxy pour le mandatement dynamique inverse de masse
Statut: | Extension
Identificateur de Module: | proxy_express_module
Fichier Source: | mod_proxy_express.c

Sommaire

Ce module crée dynamiquement en masse des mandataires inverses en faisant correspondre l'en-tête Host: de la requête HTTP à un nom de serveur et une URL d'arrière-plan stockés dans un fichier DBM. Il est ainsi plus aisé d'utiliser un grand nombre de mandataires inverses sans avoir à modifier la configuration. Il est loin de posséder autant de fonctionnalités que mod_proxy_balancer, qui propose aussi la croissance dynamique, mais il est conçu pour gérer un nombre beaucoup plus important de serveurs d'arrière-plan. Il convient parfaitement pour créer un commutateur HTTP frontal et pour les architectures Microservices.

Pour pouvoir être utilisé, ce module nécessite le chargement de mod_proxy.

Avertissement

N'activez le mandatement que si vous avez sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux pour votre réseau, et dans une plus large mesure pour Internet.

Limitations

  • Ce module n'est pas conçu pour remplacer les fonctionnalités dynamiques de mod_proxy_balancer. Par contre, il peut constituer une alternative légère et rapide à mod_rewrite lorsque ce dernier utilise la directive RewriteMap et le drapeau [P] pour le mandatement inverse à partir d'une table de correspondances.
  • Il ne supporte pas les mises en correspondance basées sur les expressions rationnelles ou les modèles.
  • Il émule :
    <VirtualHost *:80>
   ServerName front.end.server
   ProxyPass "/" "back.end.server:port"
   ProxyPassReverse "/" "back.end.server:port"
</VirtualHost>
    En d'autres termes, l'URL dans son ensemble est ajoutée à l'URL d'arrière-plan correspondante, tout ceci dans le but de proposer un commutateur mandataire inverse simple mais rapide.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • BalancerMember
  • BalancerGrowth
  • BalancerPersist
  • BalancerInherit

Directive ProxyExpressDBMFile

Description: | Chemin du fichier DBM.
Syntaxe: | ProxyExpressDBMFile <chemin>
Défaut: | None
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy_express
Compatibilité: | Disponible à partir de la version 2.3.13 d'Apache

La directive ProxyExpressDBMFile permet de définir le chemin du fichier DBM de correspondance Express. Ce fichier permet de faire correspondre le nom de serveur extrait de l'en-tête Host: de la requête entrante avec une URL d'arrière-plan.

Note

Ce fichier est élaboré à partir d'un fichier texte à l'aide de l'utilitaire httxt2dbm.

Fichier de correspondances ProxyExpress

##
##express-map.txt:
##

www1.example.com http://192.168.211.2:8080
www2.example.com http://192.168.211.12:8088
www3.example.com http://192.168.212.10

Création du fichier DBM

httxt2dbm -i express-map.txt -o emap

Configuration

ProxyExpressEnable on
ProxyExpressDBMFile emap

Directive ProxyExpressDBMType

Description: | Type de fichier DBM.
Syntaxe: | ProxyExpressDBMFile <type>
Défaut: | "default"
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy_express
Compatibilité: | Disponible à partir de la version 2.3.13 d'Apache

La directive ProxyExpressDBMType permet de définir le type de fichier DBM requis par le module. La valeur par défaut correspond au type DBM par défaut du fichier créé par l'utilitaire httxt2dbm.

Les valeurs possibles sont (mais toutes ne seront pas disponibles à l'exécution) :

Value | Description
db | Fichiers Berkeley DB
gdbm | Fichiers GDBM
ndbm | Fichiers NDBM
sdbm | Fichiers SDBM (toujours disponible)
default | type DBM par défaut

Directive ProxyExpressEnable

Description: | Active la fonctionnalité du module.
Syntaxe: | ProxyExpressEnable [on|off]
Défaut: | off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_proxy_express
Compatibilité: | Disponible à partir de la version 2.3.13 d'Apache

La directive ProxyExpressEnable permet d'activer/désactiver le module.


mod_proxy_fcgi - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_fcgi

Description: | Module fournissant le support de FastCGI à mod_proxy
Statut: | Extension
Identificateur de Module: | proxy_fcgi_module
Fichier Source: | mod_proxy_fcgi.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

Pour fonctionner, ce module nécessite le chargement de mod_proxy. Il fournit le support du protocole FastCGI.

Ainsi, pour pouvoir traiter le protocole FastCGI, mod_proxy et mod_proxy_fcgi doivent être chargés dans le serveur.

A la différence de mod_fcgid et mod_fastcgi, mod_proxy_fcgi n'est pas en mesure de démarrer le processus de l'application ; fcgistarter est fourni à cet effet sur certaines plateformes. Le framework applicatif FastCGI utilisé peut aussi fournir la gestion des processus ou des lancements de programmes externes.

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Traitement des bugs

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

Voir aussi

  • fcgistarter
  • mod_proxy
  • mod_authnz_fcgi

Exemples

Pour que ces exemples fonctionnent, vous ne devez pas oublier d'activer mod_proxy et mod_proxy_fcgi.

Instance d'application unique

ProxyPass "/mon_appli/" "fcgi://localhost:4000/"

mod_proxy_fcgi interdisant par défaut la réutilisation des connexions, lorsqu'une requête a été traitée, la connexion ne sera pas maintenue ouverte par le processus enfant httpd, et ne sera donc pas réutilisée. Cependant, si l'application FastCGI supporte les connexions httpd simultanées, vous pouvez opter pour la réutilisation des connexions comme dans l'exemple suivant :

Instance d'application unique, réutilisation des connexions (versions 2.4.11 et supérieures)

ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on

Active la réutilisation des connexions vers un serveur FCGI d'arrière-plan tel que PHP-FPM

Il faut garder à l'esprit que PHP-FPM (en février 2018) utilise un modèle du style prefork ; autrement dit, chacun de ses processus de travail ne peut gérer qu'une connexion à la fois.
Par défaut et lorsqu'il est configuré avec enablereuse=on et lorsqu'un MPM à base de threads est utilisé (comme worker ou event), mod_proxy autorise un jeu de ThreadsPerChild connexions vers le serveur d'arrière-plan pour chaque processus httpd, et par conséquent, il faut prêter une attention particulière aux situations suivantes :

  • Avec une charge en HTTP/1, il est fort probable que le nombre de connexions vers le serveur FCGI d'arrière-plan augmente jusqu'à atteindre MaxRequestWorkers.
  • Avec une charge en HTTP/2, et vue la manière dont mod_http2 est implémenté, il y a des threads de travail h2 additionnels qui peuvent forcer la création de connexions supplémentaires vers le serveur d'arrière-plan. Le nombre total de connexions que contiennent les jeux de connexions peut alors dépasser MaxRequestWorkers.

Le nombre maximum de processus de travail PHP-FPM doit être défini judicieusement car il est possible qu'ils finissent par rester dans l'état occupé ("busy") pour ne gérer que des connexions persistantes inactives, sans avoir la possibilité d'en établir de nouvelles ; ce qui se traduira pour l'utilisateur final par une pile de "HTTP request timeouts".

Dans l'exemple suivant, l'URI de la requête est transmis en tant que chemin du système de fichiers pour l'exécution du démon PHP-FPM. L'URL de la requête est implicitement ajoutée au second paramètre. PHP-FPM est à l'écoute de l'hôte et du port qui suivent fcgi://. La conservation/réutilisation des connexions est activée.

PHP-FPM

ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on

Dans l'exemple suivant, l'URI de la requête est transmis en tant que chemin du système de fichiers pour l'exécution du démon PHP-FPM. Dans ce cas cependant, PHP-FPM est à l'écoute d'un socket de domaine unix (UDS). Cette fonctionnalité est disponible à partir de la version 2.4.9. Avec cette syntaxe, si un nom d'hôte et un port sont ajoutés après fcgi://, ils seront ignorés.

PHP-FPM with UDS

ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"

La passerelle à répartition de charge nécessite le chargement du module mod_proxy_balancer et d'au moins un module fournissant un algorithme de répartition de charge, comme mod_lbmethod_byrequests en plus des modules déjà cités. mod_lbmethod_byrequests est le module par défaut et sera utilisé dans cet exemple de configuration.

Passerelle à répartition de charge vers plusieurs instances de l'application

ProxyPass "/myapp/" "balancer://myappcluster/"
<Proxy "balancer://myappcluster/">
    BalancerMember "fcgi://localhost:4000"
    BalancerMember "fcgi://localhost:4001"
</Proxy>

Vous pouvez aussi forcer le traitement d'une requête en tant que requête de mandataire inverse en créant un court-circuiteur de gestionnaire approprié. Dans l'exemple ci-dessous, toutes les requêtes pour des scripts PHP seront transmises au serveur FastCGI spécifié par mandat inverse. Cette fonctionnalité est disponible à partir de la version 2.4.10 du serveur HTTP Apache. Pour des raisons de performances, il est recommandé de définir un worker (configuration d'un mandataire) représentant le même serveur fcgi:// d'arrière-plan. Avec cette configuration, il est possible d'effectuer une correspondance directe entre l'URI et le chemin du fichier sur le serveur, et le chemin local du fichier sera alors transmis au serveur d'arrière-plan. Lorsque FastCGI est configuré ainsi, le serveur est en mesure de calculer le PATH_INFO le plus approprié.

Mandataire via un gestionnaire

<FilesMatch "\.php$">
    # Note : la seule partie variable est /path/to/app.sock
    SetHandler  "proxy:unix:/path/to/app.sock|fcgi://localhost/"
</FilesMatch>
   # Définition d'une configuration de mandataire qui convient.
   # La partie qui est mise en correspondance avec la valeur de
   # SetHandler est la partie qui suit le "pipe". Si vous devez faire
   # une distinction, "localhost" peut être changé en un nom de serveur
   # unique.
   <Proxy "fcgi://localhost/" enablereuse=on max=10>
   </Proxy>

<FilesMatch ...>
    SetHandler  "proxy:fcgi://localhost:9000"
</FilesMatch>

<FilesMatch ...>
    SetHandler  "proxy:balancer://myappcluster/"
</FilesMatch>

Variables d'environnement

En plus des directives de configuration qui contrôlent le comportement de mod_proxy, de nombreuses variables d'environnement permettent de piloter le fournisseur du protocole FCGI :

proxy-fcgi-pathinfo
Lorsqu'il est configuré via les directives ProxyPass ou ProxyPassMatch, mod_proxy_fcgi ne définit pas la variable d'environnement PATH_INFO, ce qui permet au serveur FCGI d'arrière-plan de déterminer correctement SCRIPT_NAME et Script-URI, et de se conformer à la section 3.3 de la RFC 3875. Si au contraire vous avez souhaitez que mod_proxy_fcgi génère une "estimation la plus exacte possible" de PATH_INFO, définissez la variable d'environnement proxy-fcgi-pathinfo. Ceci peut servir de contournement pour une bogue présente dans certaines implémentations de FCGI. Cette variable peut être multivaluée afin de pouvoir choisir la valeur la plus appropriée (versions 2.4.11 et supérieures) :
first-dot
PATH_INFO est extrait à partir du slash qui suit le premier "." de l'URL.
last-dot
PATH_INFO est extrait à partir du slash qui suit le dernier "." de l'URL.
full
PATH_INFO est calculé en supposant que l'URL correspond au chemin du système de fichiers.
unescape
PATH_INFO correspond à la partie chemin de l'URL avec ses séquences d'échappement décodées.
toute autre valeur
PATH_INFO correspond à la partie chemin de l'URL. Auparavant, c'était la seule option pour proxy-fcgi-pathinfo.

Directive ProxyFCGIBackendType

Description: | Spécifie le type de l'application FastCGI d'arrière-plan
Syntaxe: | ProxyFCGIBackendType FPM|GENERIC
Défaut: | ProxyFCGIBackendType FPM
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_proxy_fcgi
Compatibilité: | Disponible à partir de la version 2.4.26 du serveur HTTP Apache

Cette directive permet de spécifier le type de l'application FastCGI d'arrière-plan. Certains serveurs FastCGI, comme PHP-FPM, utilisent de manière historique des variables d'environnement exotiques pour identifier le type du serveur mandataire utilisé. Définissez cette directive à "GENERIC" si votre application n'est pas de type PHP-FPM et n'interpréter pas correctement des variables d'environnement comme SCRIPT_FILENAME ou PATH_TRANSLATED telles qu'elles sont définies par le serveur.

SCRIPT_FILENAME est un exemple de valeur modifiée par la définition de cette directive. Historiquement, lorsqu'on utilisait le module mod_proxy_fcgi, SCRIPT_FILENAME était préfixé par la chaîne "proxy:fcgi://". C'est cette variable que lisent certaines applications FastCGI génériques en tant que valeur en entrée pour leur script ; cependant, PHP-FPM peut supprimer le préfixe, puis garder en mémoire qu'il communique avec Apache. Avec les versions 2.4.21 à 2.4.25, ce préfixe était automatiquement supprimé par le serveur, empêchant ainsi PHP-FPM de détecter et interopérer avec Apache dans certains scénarios.

Directive ProxyFCGISetEnvIf

Description: | Permet d'adapter la valeur des variables envoyées aux serveurs FastCGI
Syntaxe: | ProxyFCGISetEnvIf conditional-expression [!]environment-variable-name [value-expression]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_proxy_fcgi
Compatibilité: | Disponible à partir de la version 2.4.26 du serveur HTTP Apache.

Juste avant la transmission d'une requête au serveur FastCGI configuré, le coeur du programme du serveur web définit un certain nombre de variables d'environnement en fonction de certains détails de la requête considérée. Les programmes FastCGI utilisent souvent ces variables comme données en entrée afin de déterminer quels scripts sous-jacents ils vont exécuter, ou quelles données en sortie doivent être produites.

Voici quelques exemples de variables d'environnement importantes :

  • SCRIPT_NAME
  • SCRIPT_FILENAME
  • REQUEST_URI
  • PATH_INFO
  • PATH_TRANSLATED

Cette directive permet de passer outre les variables d'environnement ci-dessus, entre autres. Elle est évaluée après la définition de la valeur initiale de ces variables ; elle peuvent donc être utilisées comme entrées dans les expressions définissants les conditions et les valeurs.

Syntaxe des paramètres :

conditional-expression
Définit une condition en fonction de laquelle la variable d'environnement qui suit sera modifiée ou non. Pour la syntaxe de cette expression, reportez-vous aux exemples qui suivent ou à la spécification détaillée dans le document ap_expr.
environment-variable-name
Spécifie le nom de la variable d'environnement à modifier, par exemple PATH_INFO. Si elle est précédée d'un point d'exclamation, la définition de la variable sera annulée.
value-expression
Spécifie la nouvelle valeur de la variable "environment-variable-name". On peut inclure des références arrières, comme "$1", issues de captures en provenance de l'expression rationnelle conditional-expression. Si cette valeur est omise, la variable est définie (ou sa valeur est écrasée) par une chaîne vide — voir cependant la note ci-après.
# Une modification basique, inconditionnelle
ProxyFCGISetEnvIf "true" PATH_INFO "/example"

# Utilisation d'une variable d'environnement pour spécifier la nouvelle valeur
ProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"

# Utilisation de captures dans la condition et de références arrières dans la
# nouvelle valeur
ProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m#(/.*prefix)(\d+)(.*)#" PATH_TRANSLATED "$1$3"

Note : Annulation définition ou valeur vide

La ligne suivante annule la définition de la variable VARIABLE, ce qui l'empêche d'être envoyée au serveur FastCGI :
ProxyFCGISetEnvIf true !VARIABLE
La ligne suivante, quant à elle, efface la valeur de la variable VARIABLE en lui affectant la chaîne vide ; cette variable VARIABLE sera alors tout de même envoyée au serveur FastCGI :
ProxyFCGISetEnvIf true VARIABLE
La spécification CGI/1.1 ne fait pas de distinction entre une variable contenant une chaîne vide et une variable qui n'existe pas. De nombreuses implémentations CGI et FastCGI font cependant cette distinction (ou permettent aux scripts de la faire). Le choix de celle que vous allez utiliser dépend de votre implémentation et de la raison qui vous pousse à modifier cette variable.


mod_proxy_fdpass - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_fdpass

Description: | Module fournissant le support des processus externes fdpass à mod_proxy
Statut: | Extension
Identificateur de Module: | proxy_fdpass_module
Fichier Source: | mod_proxy_fdpass.c
Compatibilité: | Disponible pour unix depuis la version 2.3 d'Apache

Sommaire

Pour fonctionner, ce module nécessite le chargement de mod_proxy. Il permet le passage de la socket du client vers un autre processus.

mod_proxy_fdpass utilise la capacité des sockets de domaine AF_UNIX à transmettre un descripteur de fichier ouvert afin de permettre à un autre processus de terminer le traitement de la requête.

Le module possède une interface de fournisseur proxy_fdpass_flusher qui permet éventuellement à un autre module d'envoyer les en-têtes de la réponse, ou même le début du corps de la réponse. Le fournisseur par défaut flush désactive la persistence, et envoie les en-têtes de la réponse, laissant le soin au processus externe d'envoyer le corps de la réponse.

Pour utiliser un autre fournisseur, vous devez spécifier le paramètre flusher de la directive ProxyPass.

À l'heure actuelle, la seule donnée transmise au processus externe est la socket du client. Pour recevoir une socket client, appelez recvfrom avec une structure struct cmsghdr allouée. Les versions futures de ce module pourront transmettre d'autres données que le socket client.

Traitement des bugs

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

Voir aussi

  • mod_proxy


mod_proxy_ftp - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_ftp

Description: | Module fournissant le support FTP à mod_proxy
Statut: | Extension
Identificateur de Module: | proxy_ftp_module
Fichier Source: | mod_proxy_ftp.c

Sommaire

Pour pouvoir fonctionner, ce module requiert le chargement de mod_proxy. Il fournit le support du mandatement des sites FTP. Notez que le support FTP est actuellement limité à la méthode GET.

Ainsi, pour pouvoir traiter les requêtes FTP mandatées, mod_proxy, et mod_proxy_ftp doivent être chargés dans le serveur.

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Traitement des bugs

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

Voir aussi

  • mod_proxy

Pourquoi les fichiers du type xxx ne sont-ils pas téléchargeables par FTP ?

Ce type particulier de fichier n'est probablement pas défini en temps que application/octet-stream dans le fichier de configuration mime.types de votre mandataire. La ligne suivante peut y remédier :

application/octet-stream   bin dms lha lzh exe class tgz taz

Vous pouvez aussi définir par défaut tous les types de fichiers en tant que fichiers binaires :

ForceType application/octet-stream

Comment puis-je forcer le téléchargement FTP en mode ASCII du fichier xxx ?

Dans les rares siruations où vous devez télécharger un fichier spécifique en utilisant la méthode de transfert FTP ASCII (alors que le mode transfert par défaut est binary), vous pouvez modifier le mode de transfert de mod_proxy en suffixant la requête avec ;type=a pour forcer un transfert en mode ASCII (les listings de répertoires FTP sont cependant quant à eux transmis en mode ASCII).

Comment puis-je effectuer un chargement FTP ?

Actuellement, seule la méthode GET est supportée pour FTP dans mod_proxy. Vous pouvez en revanche utiliser le chargement HTTP (POST or PUT) via un mandataire Apache.

Comment puis-je accéder par FTP à des fichiers situés en dehors de mon répertoire home ?

Un URI FTP est considéré comme relatif au répertoire home de l'utilisateur connecté. Hélas, vous ne pouvez pas utiliser /../ pour atteindre des répertoires de niveau supérieur, car les points sont interprétés par le navigateur et ne sont donc pas vraiment envoyés au serveur FTP. Pour traiter ce problème, une méthode nommée Squid %2f hack a été implémentée dans le mandataire FTP Apache ; cette solution est aussi utilisée par d'autres serveurs mandataires courants comme le Cache mandataire Squid. En préfixant par /%2f le chemin de votre requête, vous pouvez faire en sorte que le mandataire modifie le répertoire FTP racine en / (au lieu du répertoire home). Par exemple, pour extraire le fichier /etc/motd, vous pourriez utiliser l'URL :

ftp://utilisateur@serveur/%2f/etc/motd

Comment puis-je dissimuler le mot de passe FTP apparaissant en clair dans la ligne d'URL de mon navigateur ?

Apache utilise différentes stratégies pour effectuer une connexion à un serveur FTP à l'aide d'un nom d'utilisateur et d'un mot de passe. En l'absence de nom d'utilisateur et de mot de passe dans l'URL, Apache tente une connexion anonyme auprès du serveur FTP comme suit :

utilisateur : anonymous
mot de passe : apache_proxy@

Ceci fonctionne avec tous les serveurs FTP courants configurés pour accepter les connexions anonymes.

Pour une connexion personnalisée avec un nom d'utilisateur spécifique, vous pouvez intégrer ce dernier dans l'URL comme suit :

ftp://nom-utilisateur@serveur/mon-fichier

Si le serveur FTP demande un mot de passe pour ce nom d'utilisateur (ce qu'il est censé faire), Apache va renvoyer au client une réponse 401 (Autorisation requise), ce qui fera afficher au navigateur une boîte de dialogue utilisateur/mot de passe. Une fois le mot de passe saisi, la connexion est tentée à nouveau, et si elle réussit, la ressource demandée est présentée. L'avantage de cette procédure réside dans le fait que votre navigateur n'affiche pas le mot de passe en clair, ce qu'il aurait fait si vous aviez utilisé l'URL :

ftp://nom-utilisateur:mot-de-passe @serveur/mon-fichier

Note

Le mot de passe transmis de cette manière n'est pas chiffré lorsqu'il est envoyé. Il transite entre votre navigateur et le serveur mandataire Apache sous la forme d'une chaîne de texte en clair codée en base64, et entre le mandataire Apache et le serveur FTP en texte pur. Vous devez par conséquent réfléchir à deux fois avant d'accéder à votre serveur FTP via HTTP (et d'une manière générale avant d'accéder à vos fichiers personnels via FTP !) sur des canaux non sécurisés, car des oreilles indiscrètes pourraient intercepter votre mot de passe au cours de son transfert.

Pourquoi reçois-je un listing de fichiers alors que j'ai demandé le téléchargement d'un fichier ?

Apache examine l'URL de la requête afin de permettre la navigation dans les répertoires d'un serveur FTP ainsi que le téléchargement de fichiers. Si elle ressemble à un répertoire, ou contient des caractères génériques ("*?[{~"), alors Apache considère que c'est un listing qui est demandé, et non un téléchargement.

Vous pouvez désactiver le traitement spécial des noms contenant des caractères génériques. Voir à cet effet la directive ProxyFtpListOnWildcard.

Directive ProxyFtpDirCharset

Description: | Définit le jeu de caractères des listings FTP mandatés
Syntaxe: | ProxyFtpDirCharset jeu-caractères
Défaut: | ProxyFtpDirCharset ISO-8859-1
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy_ftp
Compatibilité: | Disponible depuis la version 2.2.7 d'Apache. Déplacé depuis mod_proxy à partir de la version 2.3.5 d'Apache

La directive ProxyFtpDirCharset permet de définir le jeu de caractères à utiliser pour les listings FTP en HTML générés par mod_proxy_ftp.

Directive ProxyFtpEscapeWildcards

Description: | Les caractères génériques dans les noms de fichiers doivent-ils être échappés lorsqu'ils sont envoyés au serveur FTP ?
Syntaxe: | ProxyFtpEscapeWildcards [on|off]
Défaut: | on
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy_ftp
Compatibilité: | Disponible depuis la version 2.3.3 du serveur HTTP Apache

La directive ProxyFtpEscapeWildcards permet de déterminer si les caractères génériques ("*?[{~") que contiennent les noms de fichiers demandés doivent être échappés pas un slash inversé avant d'être envoyés au serveur FTP. Il s'agit du comportement par défaut ; cependant, de nombreux serveurs FTP n'ont aucune connaissance de la notion d'échappement, et tentent de servir le fichier demandé sous sa forme littérale, en incluant les slashes inversés dans son nom.

Définissez cette directive à "off" pour permettre le téléchargement de fichiers dont les noms contiennent des caractères génériques depuis des serveurs FTP qui ne connaissent pas l'échappement des caractères génériques.

Directive ProxyFtpListOnWildcard

Description: | Les caractères génériques dans les noms de fichiers demandés doivent-ils déclencher l'affichage d'un listing ?
Syntaxe: | ProxyFtpListOnWildcard [on|off]
Défaut: | on
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy_ftp
Compatibilité: | Disponible depuis la version 2.3.3 du serveur HTTP Apache

La directive ProxyFtpListOnWildcard permet de déterminer si les caractères génériques ("*?[{~") que contiennent les noms de fichiers demandés provoquent l'affichage d'un listing de fichiers par mod_proxy_ftp au lieu de télécharger un fichier. Il s'agit de leur comportement par défaut (valeur on). Définissez cette directive à "off" pour permettre le téléchargement de fichiers même si leur nom contient des caractères génériques.


mod_proxy_hcheck - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_hcheck

Description: | Dynamic health check of Balancer members (workers) for mod_proxy
Status: | Extension
Module Identifier: | proxy_hcheck_module
Source File: | mod_proxy_hcheck.c
Compatibility: | Available in Apache 2.4.21 and later

Summary

This module provides for dynamic health checking of balancer members (workers). This can be enabled on a worker-by-worker basis. The health check is done independently of the actual reverse proxy requests.

This module requires the service of mod_watchdog.

Parameters

The health check mechanism is enabled via the use of additional BalancerMember parameters, which are configured in the standard way via ProxyPass:

A new BalancerMember status state (flag) is defined via this module: "C". When the worker is taken offline due to failures as determined by the health check module, this flag is set, and can be seen (and modified) via the balancer-manager.

Parameter | Default | Description
hcmethod None No dynamic health check performed. Choices are:
Method | Description | Note
None | No dynamic health checking done |
TCP | Check that a socket to the backend can be created: e.g. "are you up" |
OPTIONS | Send an HTTP OPTIONS request to the backend | *
HEAD | Send an HTTP HEAD request to the backend | *
GET | Send an HTTP GET request to the backend | *
*: Unless hcexpr is used, a 2xx or 3xx HTTP status will be interpreted as passing the health check
hcpasses | 1 | Number of successful health check tests before worker is re-enabled
hcfails | 1 | Number of failed health check tests before worker is disabled
hcinterval | 30 | Period of health checks in seconds (e.g. performed every 30 seconds)
hcuri | Additional URI to be appended to the worker URL for the health check.
hctemplate | Name of template, created via ProxyHCTemplate to use for setting health check parameters for this worker
hcexpr Name of expression, created via ProxyHCExpr, used to check response headers for health.
If not used, 2xx thru 3xx status codes imply success

Bugfix checklist

  • httpd changelog
  • Known issues
  • Report a bug

See also

  • mod_proxy

Usage examples

The following example shows how one might configured health checking for various backend servers:

ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}
ProxyHCExpr gdown {%{REQUEST_STATUS} =~ /^[5]/}
ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}

<Proxy balancer://foo>
  BalancerMember http://www.example.com/  hcmethod=GET hcexpr=in_maint hcuri=/status.php
  BalancerMember http://www2.example.com/  hcmethod=HEAD hcexpr=ok234 hcinterval=10
  BalancerMember http://www3.example.com/ hcmethod=TCP hcinterval=5 hcpasses=2 hcfails=3
  BalancerMember http://www4.example.com/
</Proxy>

ProxyPass "/" "balancer://foo"
ProxyPassReverse "/" "balancer://foo"

In this scenario, http://www.example.com/ is health checked by sending a GET /status.php request to that server and seeing that the returned page does not include the string Under maintenance. If it does, that server is put in health-check fail mode, and disabled. This dynamic check is performed every 30 seconds, which is the default.

http://www2.example.com/ is checked by sending a simple HEAD request every 10 seconds and making sure that the response status is 2xx, 3xx or 4xx. http://www3.example.com/ is checked every 5 seconds by simply ensuring that the socket to that server is up. If the backend is marked as "down" and it passes 2 health check, it will be re-enabled and added back into the load balancer. It takes 3 back-to-back health check failures to disable the server and move it out of rotation. Finally, http://www4.example.com/ is not dynamically checked at all.

ProxyHCExpr Directive

Description: | Creates a named condition expression to use to determine health of the backend based on its response.
Syntax: | ProxyHCExpr name {ap_expr expression}
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy_hcheck

The ProxyHCExpr directive allows for creating a named condition expression that checks the response headers of the backend server to determine its health. This named condition can then be assigned to balancer members via the hcexpr parameter

ProxyHCExpr: Allow for 2xx/3xx/4xx as passing

ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}
ProxyPass "/apps"     "http://backend.example.com/" hcexpr=ok234
The expression can use curly-parens ("{}") as quoting deliminators in addition to normal quotes.

If using a health check method (eg: GET) which results in a response body, that body itself can be checked via ap_expr using the hc() expression function, which is unique to this module.

In the following example, we send the backend a GET request and if the response body contains the phrase Under maintenance, we want to disable the backend.

ProxyHCExpr: Checking response body

ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}
ProxyPass "/apps"     "http://backend.example.com/" hcexpr=in_maint hcmethod=get hcuri=/status.php

NOTE: Since response body can quite large, it is best if used against specific status pages.

ProxyHCTemplate Directive

Description: | Creates a named template for setting various health check parameters
Syntax: | ProxyHCTemplate name parameter=setting <...>
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy_hcheck

The ProxyHCTemplate directive allows for creating a named set (template) of health check parameters that can then be assigned to balancer members via the hctemplate parameter

ProxyHCTemplate

ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5
ProxyPass "/apps"     "http://backend.example.com/" hctemplate=tcp5

ProxyHCTPsize Directive

Description: | Sets the total server-wide size of the threadpool used for the health check workers.
Syntax: | ProxyHCTPsize <size>
Context: | server config
Status: | Extension
Module: | mod_proxy_hcheck

If Apache httpd and APR are built with thread support, the health check module will offload the work of the actual checking to a threadpool associated with the Watchdog process, allowing for parallel checks. The ProxyHCTPsize directive determines the size of this threadpool. If set to 0, no threadpool is used at all, resulting in serialized health checks. The default size is 16.

ProxyHCTPsize

ProxyHCTPsize 32

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_proxy_html - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_html

Description: | Réécrit les liens HTML afin de s'assurer qu'ils soient bien adressables depuis les réseaux des clients dans un contexte de mandataire.
Statut: | Base
Identificateur de Module: | proxy_html_module
Fichier Source: | mod_proxy_html.c
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures

Sommaire

Ce module fournit un filtre en sortie permettant de réécrire les liens HTML dans un contexte de mandataire, afin de s'assurer que ces liens fonctionnent pour les utilisateurs en dehors du mandataire. Il accomplit la même tâche que la directive ProxyPassReverse d'Apache accomplit pour les en-têtes HTTP, et fait partie des composants essentiels d'un mandataire inverse.

Par exemple, si une entreprise possède un serveur d'applications nommé appserver.example.com qui n'est visible que depuis son réseau interne, et un serveur web public www.example.com, il peut être souhaitable de fournir une passerelle vers le serveur d'application à l'adresse http://www.example.com/appserver/. Lorsque le serveur d'applications présente un lien vers lui-même, ce lien doit être réécrit pour fonctionner à travers la passerelle. A cet effet, mod_proxy_html permet de réécrire <a href="http://appserver.example.com/foo/bar.html">foobar</a> en <a href="http://www.example.com/appserver/foo/bar.html">foobar</a>, ce qui permet de rendre le serveur d'applications accessible depuis l'extérieur.

mod_proxy_html a été développé à l'origine à WebÞing, dont la documentation détaillée pourra s'avérer utile aux utilisateurs.

Directive ProxyHTMLBufSize

Description: | Définit l'incrément de la taille du tampon, ainsi que sa taille initiale, pour la mise en tampon des scripts en ligne et des feuilles de style.
Syntaxe: | ProxyHTMLBufSize nb-octets
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Pour pouvoir interpréter du contenu non HTML (feuilles de style et scripts) embarqué dans des documents HTML, mod_proxy_html doit le lire et le mémoriser en entier dans un tampon. Ce tampon devra être étendu autant que nécessaire afin de pouvoir accueillir le plus grand script ou la plus grande feuille de style de la page, selon un incrément de nb-octets que cette directive permet de définir.

La valeur par défaut est 8192 et sera suffisante pour la plupart des pages. Cependant, si vous savez que vous allez mandater des pages contenant des feuilles de style et/ou scripts plus grands que 8k (cette taille s'entend pour chaque script ou feuilles de style, non pour leur ensemble), il sera plus efficace de définir une taille de tampon initiale plus grande afin d'éviter d'avoir à le redimensionner dynamiquement au cours du traitement d'une requête.

Directive ProxyHTMLCharsetOut

Description: | Spécifie un jeu de caractères pour la sortie de mod_proxy_html.
Syntaxe: | ProxyHTMLCharsetOut jeu-de-caractères | *
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet de spécifier un jeu de caractères pour la sortie de mod_proxy_html. Elle ne devrait jamais être utilisée, car tout changement par rapport à la valeur par défaut UTF-8 (Unicode - utilisé en interne par libxml2) induit une charge supplémentaire de traitement. La définition spéciale ProxyHTMLCharsetOut * permet de générer une sortie qui utilisera le même encodage que l'entrée.

Notez que tout ceci ne fonctionne que si le module mod_xml2enc est chargé.

Directive ProxyHTMLDocType

Description: Définit une déclaration de type de document HTML ou XHTML.
Syntaxe: ProxyHTMLDocType HTML|XHTML [Legacy]
OR
ProxyHTMLDocType fpi [SGML|XML]
Contexte: configuration du serveur, serveur virtuel, répertoire
Statut: Base
Module: mod_proxy_html
Compatibilité: Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Avec la première syntaxe, les documents seront déclarés de type HTML 4.01 ou XHTML 1.0 selon l'option spécifiée. Cette option détermine aussi si la syntaxe utilisée en sortie est HTML ou XHTML. Notez que le format des documents en provenance du serveur d'arrière-plan n'est pas important, car l'interpréteur le détectera automatiquement. Si le second argument optionnel est défini à "Legacy", les documents seront déclarés de type "Transitional" ; cette option peut être nécessaire si vous mandatez du contenu datant d'avant 1998, ou si vous travaillez avec des outils de création/publication déficients.

Avec la deuxième syntaxe, cette directive vous permet d'insérer votre propre FPI (Formal Public Identifier). Le second argument optionnel détermine si la syntaxe utilisée sera SGML/HTML ou XML/XHTML.

Par défaut, aucun FPI n'est inséré, étant donné qu'il vaut mieux pas de FPI du tout qu'un FPI bogué. Si par contre votre serveur d'arrière-plan génère du contenu HTML ou XHTML correct, vous pouvez définir cette directive en conséquence.

Avec la première syntaxe, mod_proxy_html va aussi mettre le code HTML en conformité avec le standard spécifié. Il ne pourra pas corriger toutes les erreurs, mais il va supprimer les éléments et attributs non conformes. Il peut aussi journaliser les autres erreurs si la directive LogLevel est définie à Debug.

Directive ProxyHTMLEnable

Description: | Permet d'activer/désactiver le filtre proxy_html.
Syntaxe: | ProxyHTMLEnable On|Off
Défaut: | ProxyHTMLEnable Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive est un simple commutateur permettant d'activer/désactiver le filtre proxy_html. Si mod_xml2enc est chargé, elle va aussi activer automatiquement le support de l'internationalisation.

Notez que le filtre proxy_html s'agira que si les données sont de type HTML (Content-Type text/html ou application/xhtml+xml), et si elles passent par un mandataire. Vous pouvez passer outre ces contraintes (à vos risques et périls) en définissant la variable d'environnement PROXY_HTML_FORCE.

Directive ProxyHTMLEvents

Description: | Spécifie les attributs à traiter comme des évènements de type scripting.
Syntaxe: | ProxyHTMLEvents attribut [attribut ...]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet de spécifier un ou plusieurs attributs à traiter comme des évènements de type scripting et de leur appliquer les règles ProxyHTMLURLMap lorsqu'elles ont été définies. Vous pouvez spécifier un nombre quelconque d'attributs dans une ou plusieurs directives ProxyHTMLEvents.

Normalement, cette directive est définie globalement. Si vous définissez ProxyHTMLEvents à plusieurs niveaux, certains niveaux l'emportant sur d'autres, vous devrez spécifier un jeu complet d'évènements pour chaque niveau.

Le fichier proxy-html.conf fournit une configuration par défaut et définit les évènements selon les standards HTML 4 et XHTML 1.

Directive ProxyHTMLExtended

Description: | Détermine si l'on doit corriger les liens dans les scripts en ligne, les feuilles de style et les évènements de type scripting.
Syntaxe: | ProxyHTMLExtended On|Off
Défaut: | ProxyHTMLExtended Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Si cette directive est définie à Off, les liens HTML sont réécrits en fonction des directives ProxyHTMLURLMap, mais les liens qui apparaissent dans le code Javascript et les feuilles de style restent inchangés.

Si elle est définie à On, tous les évènements de type scripting (définis par la directive ProxyHTMLEvents) et les scripts inclus ou les feuilles de style sont aussi traités par les règles ProxyHTMLURLMap, en fonction des drapeaux définis pour chacune d'entre elles. Ne définissez cette directive à On qu'en cas de nécessité absolue, car la charge supplémentaire induite impacte les performances.

Vous devez aussi prêter attention aux modèles de comparaison, car l'interpréteur n'a aucune notion de la forme que pourrait prendre une URL dans un script embarqué ou une feuille de style. En particulier, la comparaison étendus du caractère / a de fortes chances d'induire des correspondances erronées.

Directive ProxyHTMLFixups

Description: | Corrige les erreurs HTML simples.
Syntaxe: | ProxyHTMLFixups [lowercase] [dospath] [reset]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive accepte un à trois arguments parmi les suivants :

  • lowercaseLes Urls sont réécrites en minuscules
  • dospathLes slashes inversés dans les URLs sont remplacés par des slashes directs.
  • resetAnnule toute option définie à un niveau supérieur dans la configuration

Cette directive doit être utilisée avec prudence. Elle peut corriger certaines erreurs de création, mais risque aussi de modifier par erreur des liens corrects. Ne l'utilisez que si vous êtes sûr que le serveur d'arrière-plan est déficient.

Directive ProxyHTMLInterp

Description: | Active la réinterprétation des règles ProxyHTMLURLMap pour chaque requête.
Syntaxe: | ProxyHTMLInterp On|Off
Défaut: | ProxyHTMLInterp Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet d'activer le réinterprétation pour chaque requête des modèles source et cible de la directive ProxyHTMLURLMap.

Si la réinterprétation n'est pas activée, toutes les règles sont précompilées au démarrage du serveur. Si elle est activée, les règles doivent être recompilées pour chaque requête, ce qui induit une charge de traitement supplémentaire. Elle ne doit donc être activée que si cela s'avère nécessaire.

Directive ProxyHTMLLinks

Description: | Spécifie les éléments HTML dont les attributs d'URL doivent être réécrits.
Syntaxe: | ProxyHTMLLinks élément attribut [attribut2 ...]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet de spécifier les éléments dont les attributs d'URL doivent être réécrits en utilisant les règles standards ProxyHTMLURLMap. Vous devez définir une directive ProxyHTMLLinks pour chaque élément, mais chacune d'entre elles peut spécifier un nombre quelconque d'attributs

Normalement, cette directive est définie globalement. Si vous définissez ProxyHTMLLinks à plusieurs niveaux, certains niveaux l'emportant sur d'autres, vous devrez spécifier un jeu complet de liens pour chaque niveau.

Le fichier proxy-html.conf fournit une configuration par défaut et définit les liens HTML selon les standards HTML 4 et XHTML 1.

Exemples issus de proxy-html.conf

ProxyHTMLLinks  a          href
ProxyHTMLLinks  area       href
ProxyHTMLLinks  link       href
ProxyHTMLLinks  img        src longdesc usemap
ProxyHTMLLinks  object     classid codebase data usemap
ProxyHTMLLinks  q          cite
ProxyHTMLLinks  blockquote cite
ProxyHTMLLinks  ins        cite
ProxyHTMLLinks  del        cite
ProxyHTMLLinks  form       action
ProxyHTMLLinks  input      src usemap
ProxyHTMLLinks  head       profile
ProxyHTMLLinks  base       href
ProxyHTMLLinks  script     src for

Directive ProxyHTMLMeta

Description: | Active ou désactive une préinterprétation supplémentaire des métadonnées dans les sections HTML <head>.
Syntaxe: | ProxyHTMLMeta On|Off
Défaut: | ProxyHTMLMeta Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible à partir de la version 2.4 du serveur HTTP Apache ; proposé en tant que module tiers dans les versions 2.x précédentes.

Cette directive permet d'activer ou désactiver une préinterprétation supplémentaire des métadonnées dans les sections HTML <head>. Si cette préinterprétation n'est pas requise, définissez ProxyHTMLMeta à Off et les performances seront légèrement améliorées. Cependant, elle s'avère parfois nécessaire pour assurer un fonctionnement correct de l'internationalisation.

La directive ProxyHTMLMeta a deux effets. Le premier et le plus important est la détection des codages de caractères déclarés sous la forme

<meta http-equiv="Content-Type" content="text/html;charset=foo">

ou, dans le cas d'un document XHTML, sous la forme d'une déclaration XML. Elle n'est pas nécessaire si le jeu de caractères est déclaré explicitement dans un en-tête HTTP (ce qui est préférable) en provenance du serveur d'arrière-plan, ou si le document est en utf-8 (unicode) ou un de ses sous-ensembles comme ASCII. Vous pourrez aussi vous en passer lorsque le document utilise une valeur par défaut déclarée via la directive xml2EncDefault, avec le risque de propager une déclaration incorrecte. Une directive ProxyHTMLCharsetOut permettra d'annuler ce risque, mais pourra induire une surcharge de traitement supérieure à celle de ProxyHTMLMeta.

Le deuxième effet est l'interprétation de toutes les déclarations <meta http-equiv=...> et leur conversion en en-têtes HTTP, afin de conserver le but original de cette forme de métaélément HTML.

Avertissement

Compte tenu du fait que la directive ProxyHTMLMeta promeut tous les éléments http-equiv au rang d'en-têtes HTTP, il est conseillé de ne l'activer que si vous faites autant confiance au contenu HTML qu'à votre serveur mandataire. Avec cette directive en effet, si ce contenu est géré par des gens malintentionnés, ces derniers seront en mesure d'injecter des en-têtes HTTP arbitraires et peut-être malveillants dans les réponses de votre serveur.

Directive ProxyHTMLStripComments

Description: | Détermine si les commentaires HTML doivent être supprimés.
Syntaxe: | ProxyHTMLStripComments On|Off
Défaut: | ProxyHTMLStripComments Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Si cette directive est définie à On, mod_proxy_html supprimera les commentaires HTML. Notez que cela supprimera aussi tout script ou style inclus dans les commentaires (une monstruosité introduite en 1995/1996 avec Netscape 2 pour les navigateurs plus anciens, et encore utilisée de nos jours). Cette directive peut aussi interférer avec des processeurs basés sur les commentaires comme SSI ou ESI : assurez-vous d'exécuter ces derniers avant mod_proxy_html dans la chaîne de filtrage si vous supprimez les commentaires !

Directive ProxyHTMLURLMap

Description: | Définit une règle de réécriture des liens HTML
Syntaxe: | ProxyHTMLURLMap modèle-source modèle-cible [drapeaux] [cond]
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Base
Module: | mod_proxy_html
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Il s'agit de la directive la plus importante pour la réécriture des liens HTML. Lors de l'interprétation d'un document, chaque fois qu'un lien correspond à modèle-source, la partie du lien concernée sera réécrite en modèle-cible, en tenant compte des modifications induites par les drapeaux éventuellement spécifiés et par la directive ProxyHTMLExtended. Ne seront considérés comme des liens HTML que les éléments spécifiés via la directive ProxyHTMLLinks.

Le troisième argument optionnel permet de définir un des drapeaux suivants (les drapeaux sont sensibles à la casse) :

h

Ignore les liens HTML (les traverse sans les modifier)

e

Ignore les évènements de scripting (les traverse sans les modifier)

c

Traverse les sections de type style ou script sans les modifier.

L

Last-match. Si cette règle s'applique, aucune autre règle ne sera prise en compte (notez qu'il s'agit du comportement automatique pour les liens HTML).

l

L'opposé de L. Passe outre le comportement par défaut du changement unique pour les liens HTML.

R

Utilise des expressions rationnelles pour les modèles. modèle-source est une expression rationnelle, et modèle-cible une chaîne de remplacement qui peut être basée elle aussi sur une expression rationnelle. La mémorisation dans les expressions rationnelles est supportée : vous pouvez utiliser des parenthèses () dans le modèle-source, et récupérer la correspondance de leur contenu via les variables $1 à $9 dans le modèle-cible.

Si le drapeau R n'est pas fourni, la directive utilisera des chaînes littérales pour les différents modèles de recherche/remplacement. La logique de recherche est "commence par" dans les liens HTML, et "contient" dans les évènements de scripting et les sections de type style ou script.

x

Utilise les expressions rationnelles étendues POSIX. Ne s'applique qu'avec R.

i

Recherche de correspondance sensible à la casse. Ne s'applique qu'avec R.

n

Désactive la mémorisation dans les expressions rationnelles (pour améliorer les performances). Ne s'applique qu'avec R.

s

Recherche de correspondance dans les expressions rationnelles basée sur la ligne. Ne s'applique qu'avec R.

^

Recherche de correspondance au début seulement. Ne concerne que les recherches de correspondance par rapport à des chaînes, et ne s'applique pas aux liens HTML.

$

Recherche de correspondance à la fin seulement. Ne concerne que les recherches de correspondance par rapport à des chaînes, et ne s'applique pas aux liens HTML.

V

Insère des variables d'environnement dans le modèle-cible. Un modèle-cible de la forme ${varname|default} sera remplacé par la valeur de la variable d'environnement varname. Si cette dernière n'est pas définie, modèle-cible sera remplacé par default. La spécification de |default est facultative.

NOTE: l'insertion de variables d'environnement n'est possible que si la directive ProxyHTMLInterp a été définie à On.

v

Insère des variables d'environnement dans le modèle-source. La syntaxe du modèle est identique à la syntaxe précédente.

NOTE: l'insertion de variables d'environnement n'est possible que si la directive ProxyHTMLInterp a été définie à On.

Le quatrième argument optionnel cond définit une condition qui sera évaluée pour chaque requête, sous réserve que la directive ProxyHTMLInterp ait été définie à On. Si la condition est évaluée à FALSE, la règle ne sera pas appliquée à la requête. Si elle est évaluée à TRUE, ou si aucune condition n'est définie, la règle s'applique.

La condition est évaluée par l'interpréteur d'expression. La syntaxe simple des conditions dans mod_proxy_html 3.x pour HTTPD 2.0 et 2.2 est aussi supportée.


mod_proxy_http - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_http

Description: | Module fournissant le support HTTP à mod_proxy
Statut: | Extension
Identificateur de Module: | proxy_http_module
Fichier Source: | mod_proxy_http.c

Sommaire

Pour pouvoir fonctionner, ce module requiert le chargement de mod_proxy. Il fournit le support du mandatement des requêtes HTTP et HTTPS. mod_proxy_http supporte HTTP/0.9, HTTP/1.0 et HTTP/1.1. Il ne fournit aucune fonctionnalité de mise en cache. Si vous souhaitez mettre en oeuvre un mandataire qui assure aussi les fonctions de mise en cache, vous devez utiliser les services du module mod_cache.

Ainsi, pour pouvoir traiter les requêtes HTTP mandatées, mod_proxy, et mod_proxy_http doivent être chargés dans le serveur.

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • mod_proxy_connect

Variables d'environnement

Outre les directives de configuration qui contrôlent le comportement de mod_proxy, plusieurs variables d'environnement permettent de contrôler le fournisseur du protocole HTTP. Parmi les variables suivantes, celle qui ne nécessitent pas de valeur particulière sont définies quelle que soit la valeur qu'on leur affecte.

proxy-sendextracrlf
Provoque l'envoi par le mandataire d'une nouvelle ligne CR-LF supplémentaire à la fin de la requête. Ceci constitue un moyen de contournement d'une bogue de certains navigateurs.
force-proxy-request-1.0
Force le mandataire à envoyer des requêtes vers le serveur cible selon le protocole HTTP/1.0 et désactive les fonctionnalités propres à HTTP/1.1.
proxy-nokeepalive
Force le mandataire à fermer la connexion avec le serveur cible après chaque requête.
proxy-chain-auth
Si le mandataire requiert une authentification, il va lire et exploiter les données d'authentification pour mandataire envoyées par le client. Si proxy-chain-auth est définie, il va aussi faire suivre ces données vers le mandataire suivant dans la chaîne. Ceci peut s'avérer nécessaire si une chaîne de mandataires partagent les informations d'authentification. Avertissement concernant la sécurité : Ne définissez cette variable que si vous êtes sûr d'en avoir besoin, car elle peut provoquer la divulgation d'informations sensibles !
proxy-sendcl
Avec HTTP/1.0, toutes les requêtes qui possèdent un corps (par exemple les requêtes POST) doivent comporter un en-tête Content-Length. Cette variable d'environnement force le mandataire Apache à envoyer cet en-tête au serveur cible, sans tenir compte de ce que lui a envoyé le client. Ceci permet d'assurer la compatibilité lorsqu'on mandate un serveur cible mettant en oeuvre un protocole de type HTTP/1.0 ou inconnu. Elle peut cependant nécessiter la mise en tampon de l'intégralité de la requête par le mandataire, ce qui s'avère très inefficace pour les requêtes de grande taille.
proxy-sendchunks ou proxy-sendchunked
Cette variable constitue l'opposé de proxy-sendcl. Elle permet la transmission des corps de requêtes vers le serveur cible en utilisant un codage de transfert fractionné. Ceci permet une transmission des requêtes plus efficace, mais nécessite que le serveur cible supporte le protocole HTTP/1.1.
proxy-interim-response
Cette variable peut prendre les valeurs RFC (valeur par défaut) ou Suppress. Les versions précédentes de httpd supprimaient les réponses intermédiaires HTTP (1xx) envoyées par le serveur cible. En pratique, si un serveur cible envoie une réponse intermédiaire, il se peut qu'il étende lui-même le protocole d'une manière dont nous n'avons pas connaissance, ou tout simplement non conforme. Le comportement du mandataire est donc maintenant configurable : définissez proxy-interim-response RFC pour être totalement compatible avec le protocole, ou proxy-interim-response Suppress pour supprimer les réponses intermédiaires.
proxy-initial-not-pooled
Si cette variable est définie, aucune connexion faisant partie d'un jeu ne sera réutilisée si la requête du client est la requête initiale pour une connexion. Ceci permet d'éviter le message d'erreur "proxy: error reading status line from remote server" causé par la situation de compétition au cours de laquelle le serveur cible ferme la connexion du jeu après la vérification de la connexion par le mandataire, et avant que les données envoyées par le mandataire n'atteignent le serveur cible. Il faut cependant garder à l'esprit que la définition de cette variable dégrade les performances, particulièrement avec les clients HTTP/1.0.

Informations sur les requêtes

mod_proxy_http enregistre les informations suivantes pour journalisation via le format %{NOMVAR}n dans les directives LogFormat ou ErrorLogFormat :

proxy-source-port
Le port local utilisé pour la connexion vers le serveur d'arrière-plan.
proxy-status
Le code d'état HTTP reçu du serveur d'arrière-plan.


mod_proxy_http2 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_http2

Description: | HTTP/2 support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_http2_module
Source File: | mod_proxy_http2.c

Summary

mod_proxy_http2 supports HTTP/2 only, it does not provide any downgrades to HTTP/1.1. This means that the backend needs to support HTTP/2 because HTTP/1.1 will not be used instead.

This module requires the service of mod_proxy, so in order to get the ability of handling HTTP/2 proxy requests, mod_proxy and mod_proxy_http2 need to be both loaded by the server.

mod_proxy_http2 works with incoming fronted requests using HTTP/1.1 or HTTP/2. In both cases, requests proxied to the same backend are sent over a single TCP connection whenever possible (namely when the connection can be re-used).

Caveat: there will be no attemp to consolidate multiple HTTP/1.1 frontend requests (configured to be proxied to the same backend) into HTTP/2 streams belonging to the same HTTP/2 request. Each HTTP/1.1 frontend request will be proxied to the backend using a separate HTTP/2 request (trying to re-use the same TCP connection if possible).

This module relies on libnghttp2 to provide the core http/2 engine.

Warning

This module is experimental. Its behaviors, directives, and defaults are subject to more change from release to release relative to other standard modules. Users are encouraged to consult the "CHANGES" file for potential updates.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

Bugfix checklist

  • httpd changelog
  • Known issues
  • Report a bug

See also

  • mod_http2
  • mod_proxy
  • mod_proxy_connect

Basic Examples

The examples below demonstrate how to configure HTTP/2 for backend connections for a reverse proxy.

HTTP/2 (TLS)

ProxyPass "/app" "h2://app.example.com"
ProxyPassReverse "/app" "https://app.example.com"

HTTP/2 (cleartext)

ProxyPass "/app" "h2c://app.example.com"
ProxyPassReverse "/app" "http://app.example.com"

The schemes to configure above in ProxyPassReverse for reverse proxying h2 (or h2c) protocols are the usual https (resp. http) as expected/used by the user agent.

Request notes

mod_proxy_http creates the following request notes for logging using the %{VARNAME}n format in LogFormat or ErrorLogFormat:

proxy-source-port
The local port used for the connection to the backend server.
proxy-status
The HTTP/2 status received from the backend server.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_proxy_scgi - Serveur Apache HTTP Version 2.4

Module Apache mod_proxy_scgi

Description: | Module fournissant le support de la passerelle SCGI à mod_proxy
Statut: | Extension
Identificateur de Module: | proxy_scgi_module
Fichier Source: | mod_proxy_scgi.c
Compatibilité: | Disponible depuis la version 2.2.14 d'Apache

Sommaire

Pour pouvoir fonctionner, ce module requiert le chargement de mod_proxy. Il fournit le support du protocole SCGI, version 1.

Ainsi, pour être en mesure de traiter le protocole SCGI, mod_proxy et mod_proxy_scgi doivent être chargés dans le serveur.

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre réseau, mais aussi pour l'Internet au sens large.

Traitement des bugs

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

Voir aussi

  • mod_proxy
  • mod_proxy_balancer

Exemples

Rappelez-vous, pour que les exemples suivants puissent fonctionner, vous devez activer mod_proxy et mod_proxy_scgi.

Passerelle simple

ProxyPass /scgi-bin/ scgi://localhost:4000/

La passerelle à répartition de charge nécessite le chargement du module mod_proxy_balancer et d'au moins un module fournissant un algorithme de répartition de charge, comme mod_lbmethod_byrequests en plus des modules déjà cités. mod_lbmethod_byrequests est le module par défaut et sera utilisé dans cet exemple de configuration.

Passerelle à répartition de charge

ProxyPass "/scgi-bin/" "balancer://somecluster/"
<Proxy "balancer://somecluster">
    BalancerMember "scgi://localhost:4000"
    BalancerMember "scgi://localhost:4001"
</Proxy>

Variables d'environnement

En plus des directives de configuration qui permettent de contrôler le comportement de mod_proxy, une variable d'environnement peut aussi contrôler le fournisseur de protocole SCGI :

proxy-scgi-pathinfo
Par défaut, mod_proxy_scgi ne créera ni exportera jamais la variable d'environnement PATH_INFO. Ceci permet au serveur SCGI d'arrière-plan de déterminer correctement SCRIPT_NAME et Script-URI, et de rester en conformité avec la section 3.3 de la RFC 3875. Si au contraire vous souhaitez que mod_proxy_scgi génère une estimation la plus précise possible de PATH_INFO, définissez cette variable d'environnement. La variable doit être définie avant que la directive SetEnv ne soit effective. Il est possible d'utiliser à la place la directive SetEnvIf : SetEnvIf Request_URI . proxy-scgi-pathinfo

Directive ProxySCGIInternalRedirect

Description: | Active ou désactive les réponses de redirection interne en provenance du serveur cible.
Syntaxe: | ProxySCGIInternalRedirect On|Off|Headername
Défaut: | ProxySCGIInternalRedirect On
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy_scgi
Compatibilité: | Le paramètre Headername est disponible depuis la version 2.4.13 du serveur HTTP Apache.

La directive ProxySCGIInternalRedirect permet au serveur cible de rediriger en interne la passerelle vers une URL différente. Cette fonctionnalité trouve son origine dans mod_cgi qui redirige la réponse en interne si l'état de la réponse est OK (200), et si la réponse contient un en-tête Location (ou un autre en-tête défini) dont la valeur débute par un slash (/). Cette valeur est interprétée comme une nouvelle URL locale vers laquelle Apache httpd effectue sa redirection.

De ce point de vue, mod_proxy_scgi fait la même chose que mod_cgi, mais vous pouvez en plus désactiver la fonctionnalité ou spécifier l'utilisation d'un en-tête autre que Location.

Exemple

    ProxySCGIInternalRedirect Off
# Django et certains autres frameworks qualifient pleinement les "URLs
# locales" définies par l'application ; il faut donc utiliser un autre
# en-tête.
<Location /django-app/>
    ProxySCGIInternalRedirect X-Location
</Location>

Directive ProxySCGISendfile

Description: | Active l'évaluation du pseudo en-tête de réponse X-Sendfile
Syntaxe: | ProxySCGISendfile On|Off|nom-en-tête
Défaut: | ProxySCGISendfile Off
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Extension
Module: | mod_proxy_scgi

La directive ProxySCGISendfile permet au serveur cible SCGI de faire servir les fichiers directement par la passerelle. Ceci s'avère bénéfique en matière de performances — httpd peut alors utiliser sendfile ou d'autres optimisations, ce qui n'est pas possible si les fichiers passent par la socket du serveur cible. En outre, les fichiers ne sont transmis qu'une seule fois.

L'argument de la directive ProxySCGISendfile détermine le comportement de la passerelle :

Off
Aucun traitement particulier n'est effectué.
On
La passerelle recherche un en-tête dans la réponse du serveur cible nommé X-Sendfile, et interprète sa valeur comme le nom du fichier à servir. L'en-tête est ensuite supprimé de la réponse finale. Cet argument produit le même effet que ProxySCGISendfile X-Sendfile.
toute autre valeur
Identique à On, mais au lieu de rechercher le nom d'en-tête codé en dur X-Sendfile, c'est la valeur de l'argument qui constitue le nom de l'en-tête à rechercher.

Exemple

    # Utilise le nom d'en-tête par défaut (X-Sendfile)
    ProxySCGISendfile On

    # Utilise un nom d'en-tête différent
    ProxySCGISendfile X-Send-Static


mod_proxy_uwsgi - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_uwsgi

Description: | UWSGI gateway module for mod_proxy
Status: | Extension
Module Identifier: | proxy_uwsgi_module
Source File: | mod_proxy_uwsgi.c

Summary

This module requires the service of mod_proxy. It provides support for the UWSGI protocol.

Thus, in order to get the ability of handling the UWSGI protocol, mod_proxy and mod_proxy_uwsgi have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

Bugfix checklist

  • httpd changelog
  • Known issues
  • Report a bug

See also

  • mod_proxy
  • mod_proxy_balancer

Examples

Remember, in order to make the following examples work, you have to enable mod_proxy and mod_proxy_uwsgi.

Simple gateway

ProxyPass "/uwsgi-bin/" "uwsgi://localhost:4000/"

The balanced gateway needs mod_proxy_balancer and at least one load balancer algorithm module, such as mod_lbmethod_byrequests, in addition to the proxy modules listed above. mod_lbmethod_byrequests is the default, and will be used for this example configuration.

Balanced gateway

ProxyPass "/uwsgi-bin/" "balancer://somecluster/"
<Proxy balancer://somecluster>
    BalancerMember uwsgi://localhost:4000
    BalancerMember uwsgi://localhost:4001
</Proxy>

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_proxy_wstunnel - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_proxy_wstunnel

Description: | Websockets support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_wstunnel_module
Source File: | mod_proxy_wstunnel.c
Compatibility: | Available in httpd 2.4.5 and later

Summary

This module requires the service of mod_proxy. It provides support for the tunnelling of web socket connections to a backend websockets server. The connection is automatically upgraded to a websocket connection:

HTTP Response

Upgrade: WebSocket
Connection: Upgrade

Proxying requests to a websockets server like echo.websocket.org can be done using the ProxyPass directive:

ProxyPass "/ws2/"  "ws://echo.websocket.org/"
ProxyPass "/wss2/" "wss://echo.websocket.org/"

Load balancing for multiple backends can be achieved using mod_proxy_balancer.

In fact the module can be used to upgrade to other protocols, you can set the upgrade parameter in the ProxyPass directive to allow the module to accept other protocol. NONE means you bypass the check for the header but still upgrade to WebSocket. ANY means that Upgrade will read in the request headers and use in the response Upgrade

Bugfix checklist

  • httpd changelog
  • Known issues
  • Report a bug

See also

  • mod_proxy

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_ratelimit - Serveur Apache HTTP Version 2.4

Module Apache mod_ratelimit

Description: | Limitation de la bande passante pour les clients
Statut: | Extension
Identificateur de Module: | ratelimit_module
Fichier Source: | mod_ratelimit.c

Sommaire

Ce module fournit un filtre RATE_LIMIT pour limiter la bande passante des clients. Cette contrainte s'applique à chaque réponse HTTP au moment où elle est envoyée au client ; elle n'affecte pas les autres échanges entre le client et le serveur. La variable d'environnement rate-limit permet de spécifier, en kb/s, le débit de la connexion à simuler.

Optionnellement, il est possible, via la variable d'environnement rate-initial-burst, de définir une quantité de données en kOctets à transmettre à pleine vitesse avant de limiter la bande passante à la valeur voulue.

Exemple de configuration

<Location "/downloads">
    SetOutputFilter RATE_LIMIT
    SetEnv rate-limit 400
    SetEnv rate-initial-burst 512
</Location>
Si la valeur affectée à rate-limit dépasse la valeur maximale à affecter à un entier, la limitation de bande passante sera désactivée. Si la valeur affectée à rate-limit-burst dépasse la valeur maximale à affecter à un entier, la transmission du burst initial sans limitation de bande passante sera désactivée.


mod_reflector - Serveur Apache HTTP Version 2.4

Module Apache mod_reflector

Description: | Renvoie un corps de requête comme réponse via la pile de filtres en sortie.
Statut: | Base
Identificateur de Module: | reflector_module
Fichier Source: | mod_reflector.c
Compatibilité: | Versions 2.3 et ultérieures

Sommaire

Ce module permet de renvoyer un corps de requête au client, après l'avoir fait passer par la pile de filtres en sortie. Une chaîne de filtres configurée de manière appropriée peut être utilisée pour transformer la requête en réponse. Ce module peut ainsi être utilisé pour transformer un filtre en sortie en service HTTP.

Exemples

Service de compression
Fait passer le corps de la requête par le filtre DEFLATE pour le compresser. Cette requête nécessite un en-tête Content-Encoding contenant la valeur "gzip" pour que le filtre renvoie les données compressées.
<Location "/compress">
    SetHandler reflector
    SetOutputFilter DEFLATE
</Location>
Service d'abaissement de l'échantillonnage d'image
Fait passer le corps de la requête par un filtre d'abaissement de l'échantillonnage d'image, et renvoie le résultat au client.
<Location "/downsample">
    SetHandler reflector
    SetOutputFilter DOWNSAMPLE
</Location>

Directive ReflectorHeader

Description: | Renvoie un en-tête d'entrée dans les en-têtes de sortie
Syntaxe: | ReflectorHeader en-tête-entrée [en-tête-sortie]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Base
Module: | mod_reflector

Cette directive permet de contrôler la répercution des en-têtes de la requête dans la réponse. Le premier argument correspond au nom de l'en-tête à copier. Si le second argument (optionnel) est spécifié, il définit le nom sous lequel l'en-tête sera répercuté dans la réponse ; dans le cas contraire, c'est le nom de l'en-tête original qui sera utilisé.


mod_remoteip - Serveur Apache HTTP Version 2.4

Module Apache mod_remoteip

Description: | Remplace l'adresse IP du client pour la requête par l'adresse IP présentée par un mandataire ou un répartiteur de charge via les en-têtes de la requête.
Statut: | Base
Identificateur de Module: | remoteip_module
Fichier Source: | mod_remoteip.c

Sommaire

Ce module permet de traiter le client qui a initié la requête en tant que client original du point de vue de httpd à des fins d'autorisation et de connexion, même si ce client se trouve derrière un répartiteur de charge, un serveur frontal, ou un serveur mandataire.

Le module remplace l'adresse IP du client pour la connexion par l'adresse IP indiquée dans l'en-tête de requête configuré via la directive RemoteIPHeader.

Ce module implémente aussi la partie serveur du protocole PROXY de HAProxy via la directive RemoteIPProxyProtocol.

Une fois sa valeur modifiée comme indiqué, cette adresse IP client est utilisée pour la fonctionnalité Require ip de mod_authz_host ; elle est aussi affichée par mod_status, et enregistrée via les chaînes de formatage %a des modules mod_log_config et core. L'adresse IP client sous-jacente de la connexion est enregistrée via la chaîne de formatage %{c}a.

Il est essentiel de n'activer cette fonctionnalité que pour les requêtes en provenance des serveurs intermédiaires (mandataires, etc...) auxquels le serveur peut faire confiance, car il est trivial pour le client distant d'usurper l'identité d'un autre client.

Traitement des bugs

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

Voir aussi

  • mod_authz_host
  • mod_status
  • mod_log_config
  • Proxy Protocol Spec

Traitement des adresses distantes

Par défaut, Apache identifie le client via la valeur client_ip de la connexion, et de cette valeur découlent les valeurs remote_host et remote_logname de la connexion. Ces champs jouent un rôle dans l'authentification, l'autorisation et la journalisation, ainsi que dans d'autres traitements effectués par d'autres modules chargeables.

mod_remoteip remplace l'adresse IP client de la connexion par l'adresse IP client indiquée par exemple par un mandataire ou un répartiteur de charge pour toute la durée de la requête. Un répartiteur de charge pourra ainsi établir une connexion keepalive de longue durée avec le serveur, chaque requête conservant alors l'adresse IP client correcte bien que l'adresse IP client sous-jacente du répartiteur de charge reste inchangée.

Lorsque la valeur de l'en-tête comporte plusieurs adresses IP client séparées par des virgules, celles-ci sont traitées de la droite vers la gauche. Le traitement s'arrête lorsque l'adresse IP client courante n'est pas digne de confiance pour présenter l'adresse IP précédente. Le champ d'en-tête est alors mis à jour de façon à ne contenir que cette liste d'adresses non confirmées, ou bien, si toutes les adresses IP sont dignes de confiance, cet en-tête est tout bonnement supprimé de la requête.

Lors du remplacement de l'adresse IP client, le module stocke la liste des hôtes intermédiaires dans un mémo remoteip-proxy-ip-list, que l'on peut faire enregistrer par mod_log_config en utilisant le symbole de format %{remoteip-proxy-ip-list}n. Si l'administrateur doit stocker ceci dans un en-tête additionnel, la même valeur peut aussi être enregistrée sous la forme d'un en-tête en utilisant la directive RemoteIPProxiesHeader.

Adresses IPv4 converties au format IPv6

Avec httpd, d'une manière générale, toute adresse IPv4 convertie au format IPv6 est enregistrée sous sa forme IPv4.

Adresses internes (privées)

Tous les blocs d'adresses internes 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8 (ainsi que les adresses IPv6 en dehors du bloc public 2000::/3 block) ne sont évaluées par mod_remoteip que lorsque des mandataires internes (intranet) RemoteIPInternalProxy sont enregistrés.

Directive RemoteIPHeader

Description: | Définit le champ d'en-tête qui contiendra les adresses IP du client
Syntaxe: | RemoteIPHeader en-tête
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip

La directive RemoteIPHeader indique à mod_remoteip de traiter la valeur de l'en-tête spécifié comme l'adresse IP du client, ou comme une liste d'adresses IP clients intermédiaires, en fonction de la configuration des directives RemoteIPInternalProxy et RemoteIPTrustedProxy. Si ces deux dernières directives ne sont pas utilisées, mod_remoteip traitera tout hôte présentant une adresse non interne dans l'en-tête RemoteIPHeader comme hôte de confiance.

Si ces deux dernières directives ne sont pas utilisées, mod_remoteip traitera tout hôte présentant une adresse non interne dans l'en-tête RemoteIPHeader comme hôte de confiance.

Exemple à usage interne (répartiteur de charge)

RemoteIPHeader X-Client-IP

Exemple dans le cas d'un mandataire

RemoteIPHeader X-Forwarded-For

Directive RemoteIPInternalProxy

Description: | Déclare les adresses IP intranet clients comme dignes de confiance pour présenter la valeur RemoteIPHeader
Syntaxe: | RemoteIPInternalProxy ip-mandataire|ip-mandataire/sous-réseau|nom-hôte ...
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip

La directive RemoteIPInternalProxy permet d'ajouter une ou plusieurs adresses (ou blocs d'adresses) auxquelles on peut faire confiance pour présenter une valeur RemoteIPHeader valide de l'adresse IP du client. A la différence de la directive RemoteIPTrustedProxy, toute adresse IP présentée dans cet en-tête, y comprises les adresses intranet privées, sont considérées comme dignes de confiance lorsqu'elles sont indiquées par ces mandataires.

Exemple à usage interne (répartiteur de charge)

RemoteIPHeader X-Client-IP
RemoteIPInternalProxy 10.0.2.0/24
RemoteIPInternalProxy gateway.localdomain

Directive RemoteIPInternalProxyList

Description: | Déclare les adresses IP intranet clients comme dignes de confiance pour présenter la valeur RemoteIPHeader
Syntaxe: | RemoteIPInternalProxyList nom-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip

La directive RemoteIPInternalProxyList permet de spécifier un fichier parcouru au démarrage du serveur pour construire une liste d'adresses (ou blocs d'adresses), auxquelles on peut faire confiance pour présenter une valeur RemoteIPHeader valide de l'adresse IP du client.

Le caractère '#' indique une ligne de commentaires, sinon, toutes les lignes séparées par un caractère nouvelle ligne ou tous les éléments d'une ligne séparés par un espace sont traités de la même façon qu'avec la directive RemoteIPInternalProxy.

Exemple à usage interne (répartiteur de charge)

RemoteIPHeader X-Client-IP
RemoteIPInternalProxyList conf/trusted-proxies.lst

contenu de conf/mandataires-de-confiance.lst

         # Nos mandataires internes de confiance
         10.0.2.0/24         # Tout le monde dans le groupe de test
         passerelle.domaine-local # Le frontal répartiteur de charge

Directive RemoteIPProxiesHeader

Description: | Déclare le champ d'en-tête qui contiendra toutes les adresses IP intermédiaires
Syntaxe: | RemoteIPProxiesHeader Nom_en-tête
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip

La directive RemoteIPProxiesHeader permet de spécifier l'en-tête dans lequel mod_remoteip va collecter une liste de toutes les adresses IP clients intermédiaires auxquelles on pourra faire confiance pour résoudre l'adresse IP client de la requête. Notez que les adresses intermédiaires RemoteIPTrustedProxy sont enregistrées dans cet en-tête, alors que toute adresse intermédiaire RemoteIPInternalProxy est omise.

Exemple

RemoteIPHeader X-Forwarded-For
RemoteIPProxiesHeader X-Forwarded-By

Directive RemoteIPProxyProtocol

Description: | Active ou désactive la gestion du protocole PROXY
Syntaxe: | RemoteIPProxyProtocol On|Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip
Compatibilité: | Disponible à partir de la version 2.4.31 du serveur HTTP Apache

La directive RemoteIPProxyProtocol permet d'activer ou de désactiver la prise en compte et la gestion de l'en-tête de connexion du protocole PROXY. Si elle est définie à On, la demande du client doit envoyer l'en-tête approprié pour chaque nouvelle connexion, sinon cette dernière sera fermée à moins qu'il ne fasse partie de la liste, définie via la directive RemoteIPProxyProtocolDisableHosts, des hôtes pour lesquels le protocole PROXY est désactivé.

Bien que cette directive peut être définie au niveau de n'importe quel serveur virtuel, il est important de garder à l'esprit que, étant donné que le protocole PROXY est basé sur la connexion et agnostique quant au protocle, son activation/désactivation est basée sur le couple adresse IP/port. Cela signifie que si plusieurs serveurs virtuels à base de nom sont configurés avec le même couple adresse IP/port, et si vous activez le protocole PROXY pour l'un d'entre eux, il le sera aussi pour tous les autres (avec le même couple adresse IP/port). Cela signifie aussi que si vous tentez d'activer le protocole PROXY pour un serveur virtuel et de le désactiver pour un autre, cela ne marchera pas ; dans ce dernier cas, la dernière directive l'emporte sur les autres et une notification sera enregistrée dans le journal pour indiquer les réglages qui ont été annulés.

Listen 80
<VirtualHost *:80>
    ServerName www.example.com
    RemoteIPProxyProtocol On

    #Les requêtes pour ce serveur virtuel doivent contenir un en-tête du
    #protocole PROXY. Si ce n'est pas le cas, la connexion sera fermée.
</VirtualHost>

Listen 8080
<VirtualHost *:8080>
    ServerName www.example.com
    RemoteIPProxyProtocol On
    RemoteIPProxyProtocolExceptions 127.0.0.1 10.0.0.0/8

    #Les requêtes pour ce serveur virtuel doivent contenir un en-tête du
    #protocole PROXY. Si ce n'est pas le cas, la connexion sera fermée à moins
    que sa source ne soit localhost ou la gamme d'adresses RFC1918 10.x.x.x
</VirtualHost>

Directive RemoteIPProxyProtocolExceptions

Description: | Désactive la prise en compte de l'en-tête PROXY pour certains hôtes ou réseaux
Syntaxe: | RemoteIPProxyProtocolExceptions host|range [host|range] [host|range]
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip
Compatibilité: | RemoteIPProxyProtocolExceptions est disponible à partir de la version 2.4.31 du serveur HTTP Apache

La directive RemoteIPProxyProtocol permet de contrôler la prise en compte de l'en-tête de connexion du protocole PROXY. Il est parfois souhaitable d'exiger pour certains clients la présence de l'en-tête PROXY, mais aussi de permettre aux autres clients de se connecter sans ce dernier. Cette directive permet à l'administrateur du serveur d'autoriser cette possibilité à un hôte isolé ou à une gamme d'hôtes au format CIDR.

Directive RemoteIPTrustedProxy

Description: | Déclare les adresses IP clientes de l'intranet dignes de confiance pour présenter la valeur RemoteIPHeader
Syntaxe: | RemoteIPTrustedProxy ip-mandataire|ip-mandataire/sous-réseau|nom-hôte ...
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip

La directive RemoteIPTrustedProxy permet d'ajouter une ou plusieurs adresses, ou blocs d'adresses, auxquelles on peut faire confiance pour présenter une valeur RemoteIPHeader valide de l'adresse IP du client. A la différence de la directive RemoteIPInternalProxy, toutes les adresses IP intranet ou privées indiquées par de tels mandataires, y compris les blocs d'adresses 10/8, 172.16/12, 192.168/16, 169.254/16 et 127/8 (ou située en dehors du bloc IPv6 public 2000::/3), ne sont pas dignes de confiance en tant qu'adresses IP distantes, et se situent à gauche dans le contenu de l'en-tête RemoteIPHeader.

Exemple d'adresse de confiance (répartiteur de charge

RemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxy 10.0.2.16/28
RemoteIPTrustedProxy proxy.example.com

Directive RemoteIPTrustedProxyList

Description: | Déclare les adresses IP intranet clients comme dignes de confiance pour présenter la valeur RemoteIPHeader
Syntaxe: | RemoteIPTrustedProxyList nom-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_remoteip

La directive RemoteIPTrustedProxyList permet de spécifier un fichier parcouru au démarrage du serveur pour construire une liste d'adresses (ou blocs d'adresses), auxquelles on peut faire confiance pour présenter une valeur RemoteIPHeader valide de l'adresse IP du client.

Le caractère '#' indique une ligne de commentaires, sinon, toutes les lignes séparées par un caractère nouvelle ligne ou tous les éléments d'une ligne séparés par un espace sont traités de la même façon qu'avec la directive RemoteIPTrustedProxy.

Exemple d'adresse de confiance (répartiteur de charge

RemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxyList conf/trusted-proxies.lst

conf/mandataires-de-confiance.lst contents

# Mandataires externes identifiés
192.0.2.16/28 #groupe wap phone de mandataires
proxy.isp.example.com #un FAI bien connu


mod_reqtimeout - Serveur Apache HTTP Version 2.4

Module Apache mod_reqtimeout

Description: | Définit le délai maximum et le taux minimum de transfert des données pour la réception des requêtes
Statut: | Extension
Identificateur de Module: | reqtimeout_module
Fichier Source: | mod_reqtimeout.c
Compatibilité: | Disponible depuis la version 2.2.15 du serveur HTTP Apache

Exemples

  1. Accorde 10 secondes pour la réception des en-têtes de la requête et 30 secondes pour la réception du corps :
    RequestReadTimeout headerinit=10 body=30
  2. Accorde au moins 10 secondes pour la réception du corps de la requête. Si le client envoie des données, augmente ce délai d'une seconde pour chaque paquet de 1000 octets reçus, sans limite supérieure (sauf si une limite a été spécifiée via la directive LimitRequestBody) :
    RequestReadTimeout body=10,MinRate=1000
  3. Accorde au moins 10 secondes pour la réception de de la requête, en-têtes inclus. Si le client envoie des données, augmente ce délai d'une seconde pour chaque paquet de 500 octets reçus, mais n'alloue que 30 secondes pour la requête, en-têtes inclus :
    RequestReadTimeout header=10-30,MinRate=500
  4. En général, un serveur doit avoir ses délais d'en-tête et de corps configurés. Si les serveurs virtuels http et https utilisent une configuration commune, les délais ne doivent pas être définis trop bas :
    RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500

Directive RequestReadTimeout

Description: | Définit des délais maximums pour la réception des en-têtes et corps des requêtes en provenance du client.
Syntaxe: | RequestReadTimeout [header=délai[-délai-maxi][,MinRate=taux-mini] [body=délai[-délai-maxi][,MinRate=taux-mini]
Défaut: | header=20-40,MinRate=500 body=20,MinRate=500
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_reqtimeout
Compatibilité: | Disponible depuis la version 2.2.15 du serveur HTTP Apache ; désactivée par défaut depuis la version 2.3.14.

Cette directive permet de définir différents délais pour la réception des en-têtes et corps des requêtes en provenance du client. Si le client ne parvient pas à respecter ces délais, un code d'erreur 408 REQUEST TIME OUT est envoyé.

Pour les serveurs virtuels SSL, le délai concernant les en-têtes inclut le temps nécessaire à la négociation SSL initiale. Si le navigateur du client est configuré pour demander des listes de révocations de certificats, et si le serveur correspondant n'est pas disponible, le délai avant lequel le navigateur va abandonner son attente de CRL au cours de la négociation SSL initiale peut être assez important. Par conséquent, les valeurs de délais d'en-têtes ne doivent pas être trop basses pour les serveurs virtuels SSL. Le délai concernant le corps inclut le temps nécessaire à la renégociation SSL (si elle est nécessaire).

Lorsqu'une directive AcceptFilter est active (ce qui est en général le cas sous Linux et FreeBSD), la socket n'est envoyée au processus du serveur qu'après la réception du premier octet (ou de l'ensemble de la requête si httpready est défini). Le délai configuré pour les en-têtes via la directive RequestReadTimeout n'entre en ligne de compte qu'une fois la socket reçue par le processus du serveur.

Il existe deux méthodes pour spécifier le délai (pour l'en-tête ou le corps) :

  • Valeur de délai fixe:

    type=délai

    Le temps en secondes alloué pour la lecture des en-têtes ou du corps de la requête. La valeur 0 signifie aucune limite.

  • Désactivation du module pour un serveur virtuel ::

    header=0 body=0

    Avec cet exemple, le module mod_reqtimeout est complètement désactivé.

  • La valeur du délai qui est augmentée lorsque des données sont reçues :

    type=délai,MinRate=taux-mini

    Identique à ce qui précède, mais chaque fois que des données sont reçues, la valeur du délai est augmentée en fonction du taux-mini spécifié (en octets par seconde).

  • La valeur du délai augmente lorsque des données sont reçues, jusqu'à une limite supérieure:

    type=délai-délai-maxi,MinRate=taux-mini

    Identique à ce qui précède, mais le délai n'augmentera pas au delà de la borne supérieure du délai spécifiée.


mod_request - Serveur Apache HTTP Version 2.4

Module Apache mod_request

Description: | Filtres permettant de traiter et de mettre à disposition les corps de requêtes HTTP
Statut: | Base
Identificateur de Module: | request_module
Fichier Source: | mod_request.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Directive KeptBodySize

Description: | Conserve le corps de la requête à concurrence de la taille maximale spécifiée, pour une utilisation éventuelle par des filtres comme mod_include.
Syntaxe: | KeptBodySize taille maximale en octets
Défaut: | KeptBodySize 0
Contexte: | répertoire
Statut: | Base
Module: | mod_request

Dans une situation normale, les gestionnaires de requête tels que le gestionnaire par défaut des fichiers statiques suppriment le corps de la requête s'il n'est pas nécessaire au gestionnaire de requête. Il en résulte que les filtres comme mod_include sont limités à des requêtes GET lors de l'inclusion d'autres URLs en tant que sous-requêtes, et ceci même si la requête originale était une requête POST, car le corps de la requête a été supprimé et n'est donc plus disponible une fois le traitement du filtre mis en oeuvre.

Lorsque l'argument de cette directive a une valeur supérieure à zéro, les gestionnaires de requête qui suppriment habituellement les corps de requête vont alors conserver ces corps de requête, à concurrence de la taille maximale spécifiée, pour être éventuellement utilisés par des filtres. Dans le cas du filtre mod_include, une tentative de requête POST pour un fichier shtml statique se traduira par des sous-requêtes POST, et non par des sous-requêtes GET comme avant.

Cette fonctionnalité permet de découper des pages web complexes et des applications web en petits éléments individuels, et de combiner ces éléments avec la structure de la page web sous-jacente en utilisant mod_include. Les éléments peuvent se présenter sous la forme de programmes CGI, de langages de scripts, ou d'URLs issues d'un mandataire inverse dans l'espace d'URL d'un autre serveur en utilisant mod_proxy.

Note : Chaque requête dont le corps est ainsi conservé doit être enregistrée temporairement en mémoire vive jusqu'à la fin du traitement de la requête. Il faut donc s'assurer que la mémoire RAM du serveur est suffisante pour pouvoir supporter la charge induite. L'utilisation de cette directive doit être limitée à certaines portions de votre espace d'URL bien précises qui le nécessitent, et en spécifiant comme taille maximale une valeur la plus petite possible, mais tout de même suffisante pour un corps de requête.

Si la taille de la requête envoyée par le client dépasse la taille maximale autorisée par cette directive, le serveur renverra l'erreur 413 Request Entity Too Large.

Voir aussi

  • la documentation de mod_include
  • la documentation de mod_auth_form


mod_sed - Serveur Apache HTTP Version 2.4

Module Apache mod_sed

Description: | Filtre les contenus en entrée (requêtes) et en sortie (réponses) en utilisant la syntaxe de sed
Statut: |
Identificateur de Module: | sed_module
Fichier Source: | mod_sed.c sed0.c sed1.c regexp.c regexp.h sed.h
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

mod_sed est un filtre de contenu "in-process". Le filtre mod_sed fournit les commandes d'édition de sed implémentées par le programme sed de Solaris 10 comme décrit dans la page de manuel. Cependant, à la différence de sed, mod_sed ne reçoit pas de données sur son entrée standard. Au lieu de cela, le filtre agit sur les données échangées entre le client et le serveur. mod_sed peut être utilisé comme filtre en entrée ou en sortie. mod_sed est un filtre de contenu, ce qui signifie qu'on ne peut pas l'utiliser pour modifier les en-têtes http du client ou du serveur.

Le filtre en sortie mod_sed accepte un tronçon de données, exécute le script sed sur ces données, puis génère une sortie qui est transmise au filtre suivant dans la chaîne.

Le filtre en entrée mod_sed reçoit des données en provenance du filtre suivant dans la chaîne, exécute les scripts sed, et renvoie les données générées au filtre appelant dans la chaîne de filtrage.

Les filtres en entrée ou en sortie ne traitent les données que si des caractères newline sont détectés dans le contenu à filtrer. A la fin des données, ce qui reste est traité comme la dernière ligne.

Exemple de configuration

Ajout d'un filtre en sortie

# Dans l'exemple suivant, le filtre sed va remplacer la chaîne
     # "monday" par "MON" et la chaîne "sunday" par "SUN" dans les
     # documents html avant de les envoyer au client.
<Directory "/var/www/docs/sed">
    AddOutputFilter Sed html
    OutputSed "s/monday/MON/g"
    OutputSed "s/sunday/SUN/g"
</Directory>

Ajout d'un filtre en entrée

         # Dans l'exemple suivant, le filtre sed va remplacer la chaîne
     # "monday" par "MON" et la chaîne "sunday" par "SUN" dans les
     # données POST envoyées à PHP.
        <Directory "/var/www/docs/sed">
    AddInputFilter Sed php
    InputSed "s/monday/MON/g"
    InputSed "s/sunday/SUN/g"
</Directory>

Commandes sed

Vous trouverez tous les détails à propos de la commande sed dans sa page de manuel.

b
Saut vers le label spécifié (similaire à goto).
h
Copie la ligne courante dans le tampon.
H
Ajoute la ligne courante au tampon.
g
Copie le contenu du tampon dans la ligne courante.
G
Ajoute le contenu du tampon à la ligne courante.
x
Echange les contenus du tampon et de la ligne courante.

Directive InputSed

Description: | Commande sed à exécuter pour le filtrage des données d'une requête (en général des données POST)
Syntaxe: | InputSed commande-sed
Contexte: | répertoire, .htaccess
Statut: |
Module: | mod_sed

La directive InputSed permet de spécifier la commande sed à exécuter pour le filtrage des données (en général des données POST) d'une requête.

Directive OutputSed

Description: | Commande sed pour le filtrage des contenus de type réponse
Syntaxe: | OutputSed commande-sed
Contexte: | répertoire, .htaccess
Statut: |
Module: | mod_sed

La directive OutputSed permet de spécifier la commande sed à exécuter dans le cadre du traitement d'une réponse.


mod_session - Serveur Apache HTTP Version 2.4

Module Apache mod_session

Description: | Support des sessions
Statut: | Extension
Identificateur de Module: | session_module
Fichier Source: | mod_session.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

Avertissement

Le module session fait usage des cookies HTTP, et peut à ce titre être victime d'attaques de type Cross Site Scripting, ou divulguer des informations à caractère privé aux clients. Veuillez vous assurer que les risques ainsi encourus ont été pris en compte avant d'activer le support des sessions sur votre serveur.

Ce module fournit le support d'une interface de session pour chaque utilisateur au niveau du serveur global. Les sessions permettent de transmettre diverses informations : l'utilisateur est-il connecté ou non, ou toute autre information qui doit être conservée d'une requête à l'autre.

Les sessions peuvent être stockées sur le serveur, ou au niveau du navigateur. Les sessions peuvent également être chiffrées pour une sécurité accrue. Ces fonctionnalités sont réparties entre différents modules complémentaires de mod_session : mod_session_crypto, mod_session_cookie et mod_session_dbd. Chargez les modules appropriés en fonction des besoins du serveur (soit statiquement à la compilation, soit dynamiquement via la directive LoadModule).

Les sessions peuvent être manipulées par d'autres modules qui dépendent de la session, ou la session peut être lue et écrite dans des variables d'environnement et des en-têtes HTTP, selon les besoins.

Traitement des bugs

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

Voir aussi

  • mod_session_cookie
  • mod_session_crypto
  • mod_session_dbd

Qu'est-ce qu'une session ?

Au coeur de l'interface de session se trouve une table de paires clé/valeur qui sont accessibles d'une requête du navigateur à l'autre. Les valeurs de clés peuvent se voir affecter toute chaîne de caractères valide, en fonction des besoins de l'application qui fait usage de la session.

Une "session" est une chaîne application/x-www-form-urlencoded qui contient la paire clé/valeur définie par la spécification HTML.

Selon les souhaits de l'administrateur, la session peut être chiffrée et codée en base64 avant d'être soumise au dispositif de stockage.

Qui peut utiliser une session ?

L'interface de session a été conçue à l'origine pour être utilisée par d'autres modules du serveur comme mod_auth_form ; les applications à base de programmes CGI peuvent cependant se voir accorder l'accès au contenu d'une session via la variable d'environnement HTTP_SESSION. Il est possible de modifier et/ou de mettre à jour une session en insérant un en-tête de réponse HTTP contenant les nouveaux paramètres de session.

Stockage des sessions sur le serveur

Apache peut être configuré pour stocker les sessions utilisateurs sur un serveur particulier ou un groupe de serveurs. Cette fonctionnalité est similaire aux sessions disponibles sur les serveurs d'applications courants.

Selon la configuration, les sessions sont suivies à partir d'un identifiant de session stocké dans un cookie, ou extraites de la chaîne de paramètres de l'URL, comme dans les requêtes GET courantes.

Comme le contenu de la session est stocké exclusivement sur le serveur, il est nécessaire de préserver la confidentialité de ce contenu. Ceci a des implications en matière de performance et de consommation de ressources lorsqu'un grand nombre de sessions est stocké, ou lorsqu'un grand nombre de serveurs doivent se partager les sessions entre eux.

Le module mod_session_dbd permet de stocker les sessions utilisateurs dans une base de données SQL via le module mod_dbd.

Stockage des sessions au niveau du navigateur

Dans les environnements à haut trafic où le stockage d'une session sur un serveur consomme trop de ressources, il est possible de stocker le contenu de la session dans un cookie au niveau du navigateur client.

Ceci a pour avantage de ne nécessiter qu'une quantité minimale de ressources sur le serveur pour suivre les sessions, et évite à plusieurs serveurs parmi une forêt de serveurs de devoir partager les informations de session.

Le contenu de la session est cependant présenté au client, avec pour conséquence un risque de perte de confidentialité. Le module mod_session_crypto peut être configuré pour chiffrer le contenu de la session avant qu'elle soit stockée au niveau du client.

Le module mod_session_cookie permet de stocker les sessions au niveau du navigateur dans un cookie HTTP.

Exemples simples

La création d'une session consiste simplement à ouvrir la session, et à décider de l'endroit où elle doit être stockée. Dans l'exemple suivant, la session sera stockée au niveau du navigateur, dans un cookie nommé session.

Session stockée au niveau du navigateur

Session On
SessionCookieName session path=/

Une session est inutile s'il n'est pas possible d'y lire ou d'y écrire. L'exemple suivant montre comment des valeurs peuvent être injectées dans une session à l'aide d'un en-tête de réponse HTTP prédéterminé nommé X-Replace-Session.

Ecriture dans une session

Session On
SessionCookieName session path=/
SessionHeader X-Replace-Session

L'en-tête doit contenir des paires clé/valeur sous le même format que celui de la chaîne d'argument d'une URL, comme dans l'exemple suivant. Donner pour valeur à une clé la chaîne vide a pour effet de supprimer la clé de la session.

Script CGI pour écrire dans une session

#!/bin/bash
echo "Content-Type: text/plain"
echo "X-Replace-Session: key1=foo&key2=&key3=bar"
echo
env

Selon la configuration, les informations de la session peuvent être extraites de la variable d'environnement HTTP_SESSION. Par défaut la session est privée, et cette fonctionnalité doit donc être explicitement activée via la directive SessionEnv.

Lecture depuis une session

Session On
SessionEnv On
SessionCookieName session path=/
SessionHeader X-Replace-Session

Une fois la lecture effectuée, la variable CGI HTTP_SESSION doit contenir la valeur clé1=foo&clé3=bar.

Confidentialité des sessions

En utilisant la fonctionnalité de votre navigateur "Afficher les cookies", vous pouvez voir une réprésentation de la session sous forme de texte en clair. Ceci peut poser problème si le contenu de la session doit être dissimulé à l'utilisateur final, ou si un tiers accède sans autorisation aux informations de session.

À ce titre, le contenu de la session peut être chiffré à l'aide du module mod_session_crypto avant d'être stocké au niveau du navigateur.

Session chiffrée avant stockage au niveau du navigateur

Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/

La session sera automatiquement déchiffrée à la lecture, et rechiffrée par Apache lors de la sauvegarde, si bien que l'application sous-jacente qui utilise la session n'a pas à se préoccuper de savoir si un chiffrement a été mis en oeuvre ou non.

Les sessions stockées sur le serveur plutôt qu'au niveau du navigateur peuvent aussi être chiffrées, préservant par là-même la confidentialité lorsque des informations sensibles sont partagées entre les serveurs web d'une forêt de serveurs à l'aide du module mod_session_dbd.

Confidentialité du cookie

Le mécanisme de cookie HTTP offre aussi des fonctionnalités quant à la confidentialité, comme la possibilité de restreindre le transport du cookie aux pages protégées par SSL seulement, ou l'interdiction pour les scripts java qui s'exécutent au niveau du navigateur d'obtenir l'accès au contenu du cookie.

Avertissement

Certaines fonctionnalités de confidentialité du cookie HTTP ne sont pas standardisées, ou ne sont pas toujours implémentées au niveau du navigateur. Les modules de session vous permettent de définir les paramètres du cookie, mais il n'est pas garanti que la confidentialité sera respectée par le navigateur. Si la sécurité est la principale préoccupation, chiffrez le contenu de la session avec le module mod_session_crypto, ou stockez la session sur le serveur avec le module mod_session_dbd.

Les paramètres standards du cookie peuvent être spécifiés après le nom du cookie comme dans l'exemple suivant :

Définition des paramètres du cookie

Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/private;domain=example.com;httponly;secure;

Dans les cas où le serveur Apache sert de frontal pour des serveurs d'arrière-plan, il est possible de supprimer les cookies de session des en-têtes HTTP entrants à l'aide de la directive SessionCookieRemove. Ceci permet d'empêcher les serveurs d'arrière-plan d'accéder au contenu des cookies de session.

Support des sessions pour l'authentification

Comme il est possible de le faire avec de nombreux serveurs d'applications, les modules d'authentification peuvent utiliser une session pour stocker le nom d'utilisateur et le mot de passe après connexion. Le module mod_auth_form par exemple, sauvegarde les nom de connexion et mot de passe de l'utilisateur dans une session.

Authentification à base de formulaire

Session On
SessionCryptoPassphrase secret
SessionCookieName session path=/
AuthFormProvider file
AuthUserFile "conf/passwd"
AuthType form
AuthName realm
#...

Pour la documentation et des exemples complets, voir le module mod_auth_form.

Intégration des sessions avec les applications externes

Pour que les sessions soient utiles, leur contenu doit être accessible aux applications externes, et ces dernières doivent elles-mêmes être capables d'écrire une session.

L'exemple type est une application qui modifie le mot de passe d'un utilisateur défini par mod_auth_form. Cette application doit pouvoir extraire les nom d'utilisateur et mot de passe courants de la session, effectuer les modifications demandées, puis écrire le nouveau mot de passe dans la session, afin que la transition vers le nouveau mot de passe soit transparente.

Un autre exemple met en jeu une application qui enregistre un nouvel utilisateur pour la première fois. Une fois l'enregistrement terminé, le nom d'utilisateur et le mot de passe sont écrits dans la session, fournissant là aussi une transition transparente.

Modules Apache
Selon les besoins, les modules du serveur peuvent utiliser l'API mod_session.h pour lire et écrire dans les sessions. Les modules tels que mod_auth_form utilisent ce mécanisme.
Programmes CGI et langages de script
Les applications qui s'exécutent au sein du serveur web peuvent éventuellement extraire la valeur de la session de la variable d'environnement HTTP_SESSION. La session doit être codée sous la forme d'une chaîne application/x-www-form-urlencoded selon les préconisations de la specification HTML. Cette variable d'environnement est définie via la directive SessionEnv. Un script peut écrire dans la session en renvoyant un en-tête de réponse application/x-www-form-urlencoded dont le nom est défini via la directive SessionHeader. Dans les deux cas, tout chiffrement ou déchiffrement, ainsi que la lecture ou l'écriture de ou vers la session à partir du mécanisme de stockage choisi sont gérés par le module mod_session et la configuration correspondante.
Applications situées derrière mod_proxy
Si la directive SessionHeader est utilisée pour définir un en-tête de requête HTTP, la session codée sous la forme d'une chaîne application/x-www-form-urlencoded sera accessible pour l'application. Si ce même en-tête est fourni dans la réponse, sa valeur sera utilisée pour remplacer la session. Comme précédemment, tout chiffrement ou déchiffrement, ainsi que la lecture ou l'écriture de ou vers la session à partir du mécanisme de stockage choisi sont gérés par le module mod_session et la configuration correspondante.
Applications indépendantes
Les applications peuvent choisir de manipuler la session en s'affranchissant du contrôle du serveur HTTP Apache. Dans ce cas, c'est l'application qui doit prendre en charge la lecture de la session depuis le mécanisme de stockage choisi, son déchiffrement, sa mise à jour, son chiffrement et sa réécriture vers le mécanisme de stockage choisi de manière appropriée.

Directive Session

Description: | Ouvre une session pour le contexte courant
Syntaxe: | Session On|Off
Défaut: | Session Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_session

La directive Session permet d'ouvrir une session pour le contexte ou conteneur courant. Les directives suivantes permettent de définir où la session sera stockée et comment sera assurée la confidentialité.

Directive SessionEnv

Description: | Définit si le contenu de la session doit être enregistré dans la variable d'environnement HTTP_SESSION
Syntaxe: | SessionEnv On|Off
Défaut: | SessionEnv Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_session

Lorsque la directive SessionEnv est définie à On, le contenu de la session est enregistré dans une variable d'environnement CGI nommée HTTP_SESSION.

La chaîne est écrite sous le même format que celui de la chaîne d'arguments d'une URL, comme dans l'exemple suivant :

clé1=foo&clé3=bar

Directive SessionExclude

Description: | Définit les préfixes d'URLs pour lesquels une session sera ignorée
Syntaxe: | SessionExclude chemin
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session

La directive SessionExclude permet de définir les préfixes d'URLs pour lesquels la session sera désactivée. Ceci peut améliorer l'efficacité d'un site web, en ciblant de manière plus précise l'espace d'URL pour lequel une session devra être maintenue. Par défaut, toutes les URLs du contexte ou du conteneur courant sont incluses dans la session. La directive SessionExclude l'emporte sur la directive SessionInclude.

Avertissement

Cette directive a un comportement similaire à celui de l'attribut chemin des cookies HTTP, mais ne doit pas être confondue avec cet attribut. En effet, cette directive ne définit pas l'attribut chemin, qui doit être configuré séparément.

Directive SessionHeader

Description: | Importation des mises à jour de session depuis l'en-tête de réponse HTTP spécifié
Syntaxe: | SessionHeader en-tête
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_session

La directive SessionHeader permet de définir le nom d'un en-tête de réponse HTTP qui, s'il est présent, sera lu et son contenu écrit dans la session courante.

Le contenu de l'en-tête doit se présenter sous le même format que celui de la chaîne d'arguments d'une URL, comme dans l'exemple suivant :

clé1=foo&clé2=&clé3=bar

Si une clé a pour valeur la chaîne vide, elle sera supprimée de la session.

Directive SessionInclude

Description: | Définit les préfixes d'URL pour lesquels une session est valide
Syntaxe: | SessionInclude chemin
Défaut: | toutes URLs
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_session

La directive SessionInclude permet de définir les préfixes d'URL spécifiques pour lesquels une session sera valide. Ceci peut améliorer l'efficacité d'un site web, en ciblant de manière plus précise l'espace d'URL pour lequel une session devra être maintenue. Par défaut, toutes les URLs du contexte ou du conteneur courant sont incluses dans la session.

Avertissement

Cette directive a un comportement similaire à celui de l'attribut chemin des cookies HTTP, mais ne doit pas être confondue avec cet attribut. En effet, cette directive ne définit pas l'attribut chemin, qui doit être configuré séparément.

Directive SessionMaxAge

Description: | Définit une durée de vie maximale pour la session en secondes
Syntaxe: | SessionMaxAge durée de vie maximale
Défaut: | SessionMaxAge 0
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_session

La directive SessionMaxAge permet de définir la durée maximale pendant laquelle une session restera valide. Lorsqu'une session est sauvegardée, cette durée est réinitialisée et la session peut continuer d'exister. Si la durée d'une session dépasse cette limite sans qu'une requête au serveur ne vienne la rafraîchir, la session va passer hors délai et sera supprimée. Lorsqu'une session est utilisée pour stocker les informations de connexion d'un utilisateur, ceci aura pour effet de le déconnecter automatiquement après le délai spécifié.

Donner à cette directive la valeur 0 empêche l'expiration de la session.


mod_session_cookie - Serveur Apache HTTP Version 2.4

Module Apache mod_session_cookie

Description: | Support des sessions basé sur les cookies
Statut: | Extension
Identificateur de Module: | session_cookie_module
Fichier Source: | mod_session_cookie.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

Avertissement

Les modules de session font usage des cookies HTTP, et peuvent à ce titre être victimes d'attaques de type Cross Site Scripting, ou divulguer des informations à caractère privé aux clients. Veuillez vous assurer que les risques ainsi encourus ont été pris en compte avant d'activer le support des sessions sur votre serveur.

Ce sous-module du module mod_session fournit le support du stockage des sessions utilisateur au niveau du navigateur distant dans des cookies HTTP.

L'utilisation de cookies pour stocker les sessions décharge le serveur ou le groupe de serveurs de la nécessité de stocker les sessions localement, ou de collaborer pour partager les sessions, et peut être utile dans les environnements à fort trafic où le stockage des sessions sur le serveur pourrait s'avérer trop consommateur de ressources.

Si la confidentialité de la session doit être préservée, le contenu de cette dernière peut être chiffré avant d'être enregistré au niveau du client à l'aide du module mod_session_crypto.

Pour plus de détails à propos de l'interface des sessions, voir la documentation du module mod_session.

Traitement des bugs

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

Voir aussi

  • mod_session
  • mod_session_crypto
  • mod_session_dbd

Exemples simples

Pour créer une session et la stocker dans un cookie nommé session, configurez-la comme suit :

Session stockée au niveau du navigateur

Session On
SessionCookieName session path=/

Pour plus d'exemples sur la manière dont une session doit être configurée pour qu'une application CGI puisse l'utiliser, voir la section exemples de la documentation du module mod_session.

Pour des détails sur la manière dont une session peut être utilisée pour stocker des informations de type nom d'utilisateur/mot de passe, voir la documentation du module mod_auth_form.

Directive SessionCookieName

Description: | Nom et attributs du cookie RFC2109 dans lequel la session est stockée
Syntaxe: | SessionCookieName nom attributs
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_cookie

La directive SessionCookieName permet de spécifier le nom et les attributs optionnels d'un cookie compatible RFC2109 dans lequel la session sera stockée. Les cookies RFC2109 sont définis en utilisant l'en-tête HTTP Set-Cookie.

Une liste optionnelle d'attributs peut être spécifiée, comme dans l'exemple suivant. Ces attributs sont insérés tels quels dans le cookie, et ne sont pas interprétés par Apache. Assurez-vous que vos attributs soient définis correctement selon la spécification des cookies.

Cookie avec attributs

Session On
SessionCookieName session path=/private;domain=example.com;httponly;secure;version=1;

Directive SessionCookieName2

Description: | Nom et attributs pour le cookie RFC2965 dans lequel est stockée la session
Syntaxe: | SessionCookieName2 nom attributs
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_cookie

La directive SessionCookieName2 permet de spécifier le nom et les attributs optionnels d'un cookie compatible RFC2965 dans lequel la session sera stockée. Les cookies RFC2965 sont définis en utilisant l'en-tête HTTP Set-Cookie2.

Une liste optionnelle d'attributs peut être spécifiée, comme dans l'exemple suivant. Ces attributs sont insérés tels quels dans le cookie, et ne sont pas interprétés par Apache. Assurez-vous que vos attributs soient définis correctement selon la spécification des cookies.

Cookie2 avec attributs

Session On
SessionCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;

Directive SessionCookieRemove

Description: | Détermine si les cookies de session doivent être supprimés des en-têtes HTTP entrants
Syntaxe: | SessionCookieRemove On|Off
Défaut: | SessionCookieRemove Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_cookie

La directive SessionCookieRemove permet de déterminer si les cookies contenant la session doivent être supprimés des en-têtes pendant le traitement de la requête.

Dans le cas d'un mandataire inverse où le serveur Apache sert de frontal à un serveur d'arrière-plan, révéler le contenu du cookie de session à ce dernier peut conduire à une violation de la confidentialité. À ce titre, si cette directive est définie à "on", le cookie de session sera supprimé des en-têtes HTTP entrants.


mod_session_crypto - Serveur Apache HTTP Version 2.4

Module Apache mod_session_crypto

Description: | Support du chiffrement des sessions
Statut: | Expérimental
Identificateur de Module: | session_crypto_module
Fichier Source: | mod_session_crypto.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

Avertissement

Les modules de session font usage des cookies HTTP, et peuvent à ce titre être victimes d'attaques de type Cross Site Scripting, ou divulguer des informations à caractère privé aux clients. Veuillez vous assurer que les risques ainsi encourus ont été pris en compte avant d'activer le support des sessions sur votre serveur.

Ce sous-module du module mod_session fournit le support du chiffrement des sessions utilisateur avant de les enregistrer dans une base de données locale, ou dans un cookie HTTP au niveau du navigateur distant.

Il peut contribuer à préserver la confidentialité des sessions lorsque leur contenu doit rester privé pour l'utilisateur, ou lorsqu'une protection contre les attaques de type cross site scripting est nécessaire.

Pour plus de détails à propos de l'interface des sessions, voir la documentation du module mod_session.

Traitement des bugs

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

Voir aussi

  • mod_session
  • mod_session_cookie
  • mod_session_dbd

Utilisation de base

Pour créer une session chiffrée et la stocker dans un cookie nommé session, configurez la comme suit :

Session chiffrée stockée au niveau du serveur

Session On
SessionCookieName session path=/
SessionCryptoPassphrase secret

La session sera chiffrée avec la clé spécifiée. Il est possible de configurer plusieurs serveurs pour qu'ils puissent partager des sessions, en s'assurant que la même clé de chiffrement est utilisée sur chaque serveur.

Si la clé de chiffrement est modifiée, les sessions seront automatiquement invalidées.

Pour des détails sur la manière dont une session peut être utilisée pour stocker des informations de type nom d'utilisateur/mot de passe, voir la documentation du module mod_auth_form.

Directive SessionCryptoCipher

Description: | L'algorithme à utiliser pour le chiffrement de la session
Syntaxe: | SessionCryptoCipher algorithme
Défaut: | aes256
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Expérimental
Module: | mod_session_crypto
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive SessionCryptoCipher permet de spécifier l'algorithme à utiliser pour le chiffrement. En l'absence de spécification, l'algorithme par défaut est aes256.

L'algorithme peut être choisi, en fonction du moteur de chiffrement utilisé, parmi les valeurs suivantes :

  • 3des192
  • aes128
  • aes192
  • aes256

Directive SessionCryptoDriver

Description: | Le pilote de chiffrement à utiliser pour chiffrer les sessions
Syntaxe: | SessionCryptoDriver nom [param[=valeur]]
Défaut: | aucun
Contexte: | configuration du serveur
Statut: | Expérimental
Module: | mod_session_crypto
Compatibilité: | Disponible depuis la version 2.3.0 d'Apache

La directive SessionCryptoDriver permet de spécifier le nom du pilote à utiliser pour le chiffrement. Si aucun pilote n'est spécifié, le pilote utilisé par défaut sera le pilote recommandé compilé avec APR-util.

Le pilote de chiffrement NSS nécessite certains paramètres de configuration, qui seront spécifiés comme arguments de la directive avec des valeurs optionnelles après le nom du pilote.

NSS sans base de données de certificats

SessionCryptoDriver nss

NSS avec base de données de certificats

SessionCryptoDriver nss dir=certs

NSS avec base de données de certificats et paramètres

SessionCryptoDriver nss dir=certs clé3=clé3.db cert7=cert7.db secmod=secmod

NSS avec chemins contenant des espaces

SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod

Le pilote de chiffrement NSS peut avoir été configuré au préalable dans une autre partie du serveur, par exemple depuis mod_nss ou mod_ldap. Si c'est le cas, un avertissement sera enregistré dans le journal, et la configuration existante s'en trouvera affectée. Pour éviter cet avertissement, utilisez le paramètre noinit comme suit :

NSS avec base de données de certificats

SessionCryptoDriver nss noinit

Pour éviter la confusion, assurez-vous que tous les modules utilisant NSS soient configurés avec des paramètres identiques.

Le pilote de chiffrement openssl accepte un paramètre optionnel permettant de spécifier le moteur de chiffrement à utiliser.

OpenSSL avec spécification du moteur de chiffrement

SessionCryptoDriver openssl engine=nom-moteur

Directive SessionCryptoPassphrase

Description: | La clé utilisée pour chiffrer la session
Syntaxe: | SessionCryptoPassphrase secret [ secret ... ]
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Expérimental
Module: | mod_session_crypto
Compatibilité: | Disponible depuis la version 2.3.0 d'Apache

La directive SessionCryptoPassphrase permet de spécifier les clés à utiliser pour chiffrer de manière symétrique le contenu de la session avant de l'enregistrer, ou pour déchiffrer le contenu de la session après sa lecture.

L'utilisation de clés longues et composées de caractères vraiment aléatoires est plus performant en matière de sécurité. Modifier une clé sur un serveur a pour effet d'invalider toutes les sessions existantes.

Il est possible de spécifier plusieurs clés afin de mettre en oeuvre la rotation de clés. La première clé spécifiée sera utilisée pour le chiffrement, alors que l'ensemble des clés spécifiées le sera pour le déchiffrement. Pour effectuer une rotation périodique des clés sur plusieurs serveurs, ajoutez une nouvelle clé en fin de liste, puis, une fois la rotation complète effectuée, supprimez la première clé de la liste.

Depuis la version 2.4.7, si la valeur de l'argument commence par exec: , la commande spécifiée sera exécutée, et la première ligne que cette dernière renverra sur la sortie standard sera utilisée comme clé.

# clé spécifiée et utilisée en tant que tel
SessionCryptoPassphrase secret

# exécution de /path/to/program pour générer la clé
SessionCryptoPassphrase exec:/path/to/program

# exécution de /path/to/program avec un argument pour générer la clé
SessionCryptoPassphrase "exec:/path/to/otherProgram argument1"

Directive SessionCryptoPassphraseFile

Description: | Le fichier contenant les clés utilisées pour chiffrer la session
Syntaxe: | SessionCryptoPassphraseFile nom-fichier
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire
Statut: | Expérimental
Module: | mod_session_crypto
Compatibilité: | Disponible depuis la version 2.3.0 du serveur HTTP Apache

La directive SessionCryptoPassphraseFile permet de spécifier le nom d'un fichier de configuration contenant les clés à utiliser pour le chiffrement et le déchiffrement de la session (une clé par ligne). Le fichier est lu au démarrage du serveur, et un redémarrage graceful est nécessaire pour prendre en compte un éventuel changement de clés.

À la différence de la directive SessionCryptoPassphrase, les clés ne sont pas présentes dans le fichier de configuration de httpd et peuvent être cachées via une protection appropriée du fichier de clés.

Il est possible de spécifier plusieurs clés afin de mettre en oeuvre la rotation de clés. La première clé spécifiée sera utilisée pour le chiffrement, alors que l'ensemble des clés spécifiées le sera pour le déchiffrement. Pour effectuer une rotation périodique des clés sur plusieurs serveurs, ajoutez une nouvelle clé en fin de liste, puis, une fois la rotation complète effectuée, supprimez la première clé de la liste.


mod_session_dbd - Serveur Apache HTTP Version 2.4

Module Apache mod_session_dbd

Description: | Support des session basé sur DBD/SQL
Statut: | Extension
Identificateur de Module: | session_dbd_module
Fichier Source: | mod_session_dbd.c
Compatibilité: | Disponible depuis la version 2.3 d'Apache

Sommaire

Avertissement

Les modules de session font usage des cookies HTTP, et peuvent à ce titre être victimes d'attaques de type Cross Site Scripting, ou divulguer des informations à caractère privé aux clients. Veuillez vous assurer que les risques ainsi encourus ont été pris en compte avant d'activer le support des sessions sur votre serveur.

Ce sous-module du module mod_session fournit le support du stockage des sessions utilisateur dans une base de données SQL en utilisant le module mod_dbd.

Les sessions sont soit anonymes, et la session est alors identifiée par un UUID unique stocké dans un cookie au niveau du navigateur, soit propres à l'utilisateur, et la session est alors identifiée par l'identifiant de l'utilisateur connecté.

Les sessions basées sur SQL sont dissimulées au navigateur, et permettent ainsi de préserver la confidentialité sans avoir recours au chiffrement.

Plusieurs serveurs web d'une forêt de serveurs peuvent choisir de partager une base de données, et ainsi partager les sessions entre eux.

Pour plus de détails à propos de l'interface des sessions, voir la documentation du module mod_session.

Traitement des bugs

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

Voir aussi

  • mod_session
  • mod_session_crypto
  • mod_session_cookie
  • mod_dbd

Configuration de DBD

Pour que le module mod_session_dbd puisse être configuré et maintenir une session, il faut tout d'abord configurer le module mod_dbd pour que le serveur puisse exécuter des requêtes vers la base de données.

Quatre types de requêtes sont nécessaires pour maintenir une session, sélectionner ou mettre à jour une session existante, insérer une nouvelle session et supprimer une session vide ou arrivée à expiration. Ces requêtes sont configurées comme dans l'exemple suivant :

Exemple de configuration de DBD

DBDriver pgsql
DBDParams "dbname=apachesession user=apache password=xxxxx host=localhost"
DBDPrepareSQL "delete from session where key = %s" deletesession
DBDPrepareSQL "update session set value = %s, expiry = %lld, key = %s where key = %s" updatesession
DBDPrepareSQL "insert into session (value, expiry, key) values (%s, %lld, %s)" insertsession
DBDPrepareSQL "select value from session where key = %s and (expiry = 0 or expiry > %lld)" selectsession
DBDPrepareSQL "delete from session where expiry != 0 and expiry < %lld" cleansession

Sessions anonymes

Les sessions anonymes sont identifiées par un UUID unique, et stockées dans un cookie au niveau du navigateur. Cette méthode est similaire à celle utilisée par la plupart des serveurs d'applications pour stocker les informations de session.

Pour créer une session anonyme, la stocker dans une table de base de donnée postgres nommée apachesession, et sauvegarder l'identifiant de session dans un cookie nommé session, configurez la session comme suit :

Session anonyme basée sur SQL

Session On
SessionDBDCookieName session path=/

Pour plus d'exemples sur la manière dont une application CGI peut accéder aux informations de session, voir la section exemples de la documentation du module mod_session.

Pour des détails sur la manière dont une session peut être utilisée pour stocker des informations de type nom d'utilisateur/mot de passe, voir la documentation du module mod_auth_form.

Sessions propres à un utilisateur

Les sessions propres à un utilisateur sont identifiées par le nom de l'utilisateur authentifié avec succès. Ceci permet d'assurer une confidentialité optimale, car aucun traitement externe à la session n'existe en dehors du contexte authentifié.

Les sessions propres à un utilisateur ne fonctionnent que dans un environnement d'authentification correctement configuré, qu'il s'agisse d'une authentification de base, à base de condensés (digest) ou de certificats client SSL. Suite à des limitations dues à des dépendances mutuelles, les sessions propres à un utilisateur ne peuvent pas être utilisées pour stocker les données d'authentification en provenance d'un module comme mod_auth_form.

Pour créer une session propre à un utilisateur, la stocker dans une table de base de données postgres nommée apachesession, avec comme clé de session l'identifiant utilisateur, ajoutez les lignes suivantes :

Session propre à un utilisateur basée sur SQL

Session On
SessionDBDPerUser On

Nettoyage de la base de données

Avec le temps, la base de données va commencer à accumuler des sessions expirées. Pour le moment, le module mod_session_dbd n'est pas en mesure de gérer automatiquement l'expiration des sessions.

Avertissement

L'administrateur devra mettre en oeuvre un traitement externe via cron pour nettoyer les sessions expirées.

Directive SessionDBDCookieName

Description: | Nom et attributs du cookie RFC2109 qui contient l'identifiant de session
Syntaxe: | SessionDBDCookieName nom attributs
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDCookieName permet de spécifier le nom et les attributs optionnels d'un cookie compatible RFC2109 qui contiendra l'identifiant de session. Les cookies RFC2109 sont définis à l'aide de l'en-tête HTTP Set-Cookie.

Une liste optionnelle d'attributs peut être spécifiée pour ce cookie, comme dans l'exemple ci-dessous. Ces attributs sont insérés dans le cookie tels quels, et ne sont pas interprétés par Apache. Assurez-vous que vos attributs sont définis correctement selon la spécification des cookies.

Cookie avec attributs

Session On
SessionDBDCookieName session path=/private;domain=example.com;httponly;secure;version=1;

Directive SessionDBDCookieName2

Description: | Nom et attributs du cookie RFC2965 qui contient l'identifiant de session
Syntaxe: | SessionDBDCookieName2 nom attributs
Défaut: | none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDCookieName2 permet de spécifier le nom et les attributs optionnels d'un cookie compatible RFC2965 qui contiendra l'identifiant de session. Les cookies RFC2965 sont définis à l'aide de l'en-tête HTTP Set-Cookie2.

Une liste optionnelle d'attributs peut être spécifiée pour ce cookie, comme dans l'exemple ci-dessous. Ces attributs sont insérés dans le cookie tel quel, et ne sont pas interprétés par Apache. Assurez-vous que vos attributs sont définis correctement selon la spécification des cookies.

Cookie2 avec attributs

Session On
SessionDBDCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;

Directive SessionDBDCookieRemove

Description: | Détermine si les cookies de session doivent être supprimés des en-têtes HTTP entrants
Syntaxe: | SessionDBDCookieRemove On|Off
Défaut: | SessionDBDCookieRemove On
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDCookieRemove permet de déterminer si les cookies contenant l'identifiant de session doivent être supprimés des en-têtes pendant le traitement de la requête.

Dans le cas d'un mandataire inverse où le serveur Apache sert de frontal à un serveur d'arrière-plan, révéler le contenu du cookie de session à ce dernier peut conduire à une violation de la confidentialité. À ce titre, si cette directive est définie à "on", le cookie de session sera supprimé des en-têtes HTTP entrants.

Directive SessionDBDDeleteLabel

Description: | La requête SQL à utiliser pour supprimer des sessions de la base de données
Syntaxe: | SessionDBDDeleteLabel étiquette
Défaut: | SessionDBDDeleteLabel deletesession
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDDeleteLabel permet de définir l'étiquette de la requête de suppression à utiliser par défaut pour supprimer une session vide ou expirée. Cette étiquette doit avoir été définie au préalable via une directive DBDPrepareSQL.

Directive SessionDBDInsertLabel

Description: | La requête SQL à utiliser pour insérer des sessions dans la base de données
Syntaxe: | SessionDBDInsertLabel étiquette
Défaut: | SessionDBDInsertLabel insertsession
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDInsertLabel permet de définir l'étiquette de la requête d'insertion par défaut à charger dans une session. Cette étiquette doit avoir été définie au préalable via une directive DBDPrepareSQL.

Si une tentative de mise à jour d'une session ne concerne aucun enregistrement, c'est cette requête qui sera utilisée pour insérer la session dans la base de données.

Directive SessionDBDPerUser

Description: | Active une session propre à un utilisateur
Syntaxe: | SessionDBDPerUser On|Off
Défaut: | SessionDBDPerUser Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDPerUser permet d'activer une session propre à un utilisateur, dont la clé sera le nom de l'utilisateur connecté. Si l'utilisateur n'est pas connecté, la directive sera ignorée.

Directive SessionDBDSelectLabel

Description: | La requête SQL à utiliser pour sélectionner des sessions dans la base de données
Syntaxe: | SessionDBDSelectLabel étiquette
Défaut: | SessionDBDSelectLabel selectsession
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDSelectLabel permet de définir l'étiquette de la requête de sélection par défaut à utiliser pour charger une session. Cette étiquette doit avoir été définie au préalable via une directive DBDPrepareSQL.

Directive SessionDBDUpdateLabel

Description: | La requête SQL à utiliser pour mettre à jour des sessions préexistantes dans la base de données
Syntaxe: | SessionDBDUpdateLabel étiquette
Défaut: | SessionDBDUpdateLabel updatesession
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Extension
Module: | mod_session_dbd

La directive SessionDBDUpdateLabel permet de définir l'étiquette de la requête de mise à jour par défaut à charger dans une session. Cette étiquette doit avoir été définie au préalable via une directive DBDPrepareSQL.

Si une tentative de mise à jour d'une session ne concerne aucun enregistrement, c'est la requête d'insertion qui sera appelée pour insérer la session dans la base de données. Si la base de données supporte InsertOrUpdate, modifiez cette requête pour effectuer la mise à jour en une seule requête au lieu de deux.


mod_setenvif - Serveur Apache HTTP Version 2.4

Module Apache mod_setenvif

Description: | Permet de définir des variables d'environnement en fonction de certainescaractéristiques de la requête
Statut: | Base
Identificateur de Module: | setenvif_module
Fichier Source: | mod_setenvif.c

Sommaire

Le module mod_setenvif vous permet de définir des variables d'environnement internes de manière conditionnelle en fonction de critères que vous pouvez spécifier. Ces variables d'environnement peuvent être utilisées par d'autres parties du serveur pour prendre des décisions quant aux actions à entreprendre, et pour déterminer si les scripts CGI et les pages SSI doivent pouvoir y accéder.

Les directives sont interprétées selon l'ordre dans lequel elles apparaîssent dans les fichiers de configuration. Ainsi, des séquences plus complexes peuvent être utilisées, comme dans cet exemple qui définit netscape si le navigateur est Mozilla et non MSIE.

BrowserMatch ^Mozilla netscape
BrowserMatch MSIE !netscape

Lorsque le serveur cherche un chemin via une sous-requête interne (par exemple la recherche d'un DirectoryIndex), ou lorsqu'il génère un listing du contenu d'un répertoire via le module mod_autoindex, la sous-requête n'hérite pas des variables d'environnement spécifiques à la requête. En outre, à cause des phases de l'API auxquelles mod_setenvif prend part, les directives SetEnvIf ne sont pas évaluées séparément dans la sous-requête.

Traitement des bugs

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

Voir aussi

  • Les variables d'environnement et le serveur HTTP Apache

Directive BrowserMatch

Description: | Définit des variables d'environnement en fonction du contenu de l'en-tête HTTP User-Agent
Syntaxe: | BrowserMatch regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_setenvif

La directive BrowserMatch est un cas particulier de la directive SetEnvIf, qui définit des variables d'environnement en fonction du contenu de l'en-tête de requête HTTP User-Agent. Les deux lignes suivantes produisent le même effet :

BrowserMatch Robot is_a_robot
SetEnvIf User-Agent Robot is_a_robot

Quelques exemples supplémentaires :

BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
BrowserMatch MSIE !javascript

Directive BrowserMatchNoCase

Description: | Définit des variables d'environnement en fonction du contenu de l'en-tête HTTP User-Agent sans tenir compte de la casse
Syntaxe: | BrowserMatchNoCase regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_setenvif

La directive BrowserMatchNoCase est identique sur le plan sémantique à la directive BrowserMatch. Elle permet cependant une comparaison insensible à la casse. Par exemple :

BrowserMatchNoCase mac platform=macintosh
BrowserMatchNoCase win platform=windows

Les directives BrowserMatch et BrowserMatchNoCase sont des cas particuliers des directives SetEnvIf et SetEnvIfNoCase. Ainsi, les deux lignes suivantes produisent le même effet :

BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot

Directive SetEnvIf

Description: | Définit des variables d'environnement en fonction des attributs de la requête
Syntaxe: | SetEnvIf attribut regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_setenvif

La directive SetEnvIf permet de définir des variables d'environnement en fonction des attributs de la requête. L'attribut spécifié comme premier argument peut se présenter sous l'une des trois formes suivantes :

  1. Un champ d'en-tête de requête HTTP (voir la RFC2616 pour plus d'information à leur propos) ; par exemple : Host, User-Agent, Referer, ou Accept-Language. Il est possible d'utiliser une expression rationnelle pour spécifier un jeu d'en-têtes de requête.
  2. Une des caractéristiques de la requête suivantes :
    • Remote_Host - le nom d'hôte (s'il est disponible) du client qui effectue la requête
    • Remote_Addr - l'adresse IP du client qui effectue la requête
    • Server_Addr - l'adresse IP du serveur qui a reçu la requête (uniquement à partir des versions supérieures à 2.0.43)
    • Request_Method - Le nom de la méthode HTTP utilisée (GET, POST, et cetera...)
    • Request_Protocol - le nom et la version du protocole utilisé pour la requête (par exemple "HTTP/0.9", "HTTP/1.1", etc...)
    • Request_URI - la ressource demandée dans la ligne de requête HTTP -- en général la partie de l'URL suivant le protocole et le nom du serveur, sans la chaîne d'arguments. Voir la directive RewriteCond du module mod_rewrite pour plus d'informations sur la manière de mettre en correspondance votre chaîne d'arguments.
  3. Le nom d'une variable d'environnement parmi la liste de celles qui sont associées à la requête. Ceci permet à la directive SetEnvIf d'effectuer des tests en fonction du résultat de comparaisons précédentes. Seules les variables d'environnement définies par des directives SetEnvIf[NoCase] précédentes sont disponibles pour effectuer des tests de cette manière. 'Précédentes' signifie qu'elles se trouvent à un niveau plus global de la configuration (par exemple au niveau du serveur principal), ou plus haut chronologiquement dans le contexte de la directive. Les variables d'environnement ne seront prises en compte que si aucune correspondance n'a été trouvée parmi les caractéristiques de la requête, et si attribut n'a pas été spécifié sous la forme d'une expression rationnelle.

Le second argument (regex) est une expression rationnelle. Si regex correspond à l'attribut, les arguments suivants sont évalués.

Le reste des arguments constitue les noms des variables à définir, ainsi que les valeurs optionnelles qui doivent leur être affectées. Ils peuvent se présenter sous les formes suivantes :

  1. nom-variable, ou
  2. !nom-variable, ou
  3. nom-variable=valeur

Dans la première forme, la valeur sera définie à "1". Dans la seconde forme, la variable sera supprimée si elle a été définie au préalable, et dans la troisième forme, la variable sera définie à la valeur littérale spécifiée par valeur. Depuis la version 2.0.51, Apache httpd reconnaît les occurrences de variables $1..$9 à l'intérieur de valeur, et les remplace par les sous-expressions entre parenthèses correspondantes de regex. $0 permet d'accéder à l'ensemble de la chaîne qui correspond à ce modèle.

SetEnvIf Request_URI "\.gif$" object_is_image=gif
SetEnvIf Request_URI "\.jpg$" object_is_image=jpg
SetEnvIf Request_URI "\.xbm$" object_is_image=xbm

SetEnvIf Referer www\.mydomain\.example\.com intra_site_referral

SetEnvIf object_is_image xbm XBIT_PROCESSING=1

SetEnvIf Request_URI "\.(.*)$" EXTENSION=$1

SetEnvIf ^TS  ^[a-z]  HAVE_TS

Les trois premières lignes définissent la variable d'environnement objet_est_une_image si l'objet de la requête est un fichier image, et la quatrième définit la variable intra_site_referral si la page référante se trouve quelque part dans le site web www.mydomain.example.com.

La dernière ligne définit la variable d'environnement HAVE_TS si la requête contient un en-tête dont le nom commence par "TS" et dont la valeur commence par tout caractère du jeu [a-z].

Voir aussi

  • Les variables d'environnement et le serveur HTTP Apache pour des exemples supplémentaires.

Directive SetEnvIfExpr

Description: | Définit des variables d'environnement en fonction d'une expression ap_expr
Syntaxe: | SetEnvIfExpr expr [!]env-variable[=valeur] [[!]env-variable[=valeur]] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_setenvif

La directive SetEnvIfExpr permet de définir des variables d'environnement en fonction d'une expression <If> ap_expr. Cette expression est évaluée à l'exécution, et utilise les variables d'environnement env-variable de la même manière que la directive SetEnvIf.

SetEnvIfExpr "tolower(req('X-Sendfile')) == 'd:\images\very_big.iso')" iso_delivered

Dans cet exemple, la variable d'environnement iso_delivered est définie chaque fois que notre application tente de l'envoyer via X-Sendfile.

Il pourrait être plus utile de définir une variable rfc1918 si l'adresse IP distante est une adresse privée au sens de la RFC 1918 :

SetEnvIfExpr "-R '10.0.0.0/8' || -R '172.16.0.0/12' || -R '192.168.0.0/16'" rfc1918

Voir aussi

  • Les expressions dans le serveur HTTP Apache, pour une référence complète et davantage d'exemples.
  • La directive <If> permet d'obtenir des résultats similaires.
  • mod_filter

Directive SetEnvIfNoCase

Description: | Définit des variables d'environnement en fonction des attributs de la requête sans tenir compte de la casse
Syntaxe: | SetEnvIfNoCase attribut regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Base
Module: | mod_setenvif

La directive SetEnvIfNoCase est identique d'un point de vue sémantique à la directive SetEnvIf, et ne s'en distingue que par le fait que la comparaison des expressions rationnelles est effectuée sans tenir compte de la casse. Par exemple :

SetEnvIfNoCase Host Example\.Org site=example

Cette ligne va définir la variable d'environnement site avec la valeur "example" si le champ d'en-tête de requête HTTP Host: est présent et contient Example.Org, example.org, ou une autre combinaison des mêmes caractères, sans tenir compte de la casse.


mod_slotmem_plain - Serveur Apache HTTP Version 2.4

Module Apache mod_slotmem_plain

Description: | Fournisseur de mémoire partagée à base de slots.
Statut: | Extension
Identificateur de Module: | slotmem_plain_module
Fichier Source: | mod_slotmem_plain.c

Sommaire

mod_slotmem_plain est un fournisseur de mémoire qui permet la création et l'utilisation d'un segment de mémoire contigu dans lequel les ensembles de données sont organisés en "slots".

Si la mémoire doit être partagée entre des threads et des processus, il est préférable d'utiliser le fournisseur mod_slotmem_shm.

mod_slotmem_plain fournit une API comprenant les fonctions suivantes :

apr_status_t doall(ap_slotmem_instance_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool)
appelle le callback sur tous les slots actifs
apr_status_t create(ap_slotmem_instance_t **new, const char *name, apr_size_t item_size, unsigned int item_num, ap_slotmem_type_t type, apr_pool_t *pool)
crée un nouveau slot de mémoire dont chaque objet aura une taille de item_size.
apr_status_t attach(ap_slotmem_instance_t **new, const char *name, apr_size_t *item_size, unsigned int *item_num, apr_pool_t *pool)
rattache à un slot de mémoire existant.
apr_status_t dptr(ap_slotmem_instance_t *s, unsigned int item_id, void**mem)
indique la mémoire associée à ce slot actif.
apr_status_t get(ap_slotmem_instance_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len)
lit la mémoire depuis ce slot et la transfère vers dest
apr_status_t put(ap_slotmem_instance_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len)
écrit dans ce slot la mémoire en provenance de src
unsigned int num_slots(ap_slotmem_instance_t *s)
renvoie le nombre total de slots contenus dans ce segment
apr_size_t slot_size(ap_slotmem_instance_t *s)
renvoie la taille totale des données, en octets, contenues dans un slot de ce segment
apr_status_t grab(ap_slotmem_instance_t *s, unsigned int *item_id);
alloue le premier slot disponible et le marque comme utilisé (n'effectue aucune copie de données)
apr_status_t fgrab(ap_slotmem_instance_t *s, unsigned int item_id);
force l'allocation ou l'appropriation du slot spécifié et le marque comme utilisé (n'effectue aucune copie de données)
apr_status_t release(ap_slotmem_instance_t *s, unsigned int item_id);
libère un slot et le marque comme non utilisé (n'effectue aucune copie de données)


mod_slotmem_shm - Serveur Apache HTTP Version 2.4

Module Apache mod_slotmem_shm

Description: | Fournisseur de mémoire partagée basée sur les slots.
Statut: | Extension
Identificateur de Module: | slotmem_shm_module
Fichier Source: | mod_slotmem_shm.c

Sommaire

mod_slotmem_shm est un fournisseur de mémoire qui permet la création et l'accès à un segment de mémoire partagée dans lequel les ensembles de données sont organisés en "slots".

L'ensemble de la mémoire partagée est effacé à chaque redémarrage, que ce dernier soit graceful ou non. Les données sont stockées et restituées dans et à partir d'un fichier défini par le paramètre name des appels create et attach. Si son chemin absolu n'est pas spécifié, le chemin du fichier sera relatif au chemin défini par la directive DefaultRuntimeDir.

mod_slotmem_shm fournit les fonctions d'API suivantes :

apr_status_t doall(ap_slotmem_instance_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool)
appelle le callback pour tous les slots actifs
apr_status_t create(ap_slotmem_instance_t **new, const char *name, apr_size_t item_size, unsigned int item_num, ap_slotmem_type_t type, apr_pool_t *pool)
crée un nouveau slot de mémoire dont chaque taille d'objet est item_size. name est utilisé pour générer le nom du fichier permettant de stocker/restaurer le contenu de la mémoire partagée si la configuration le spécifie. Les valeurs possibles sont :
"none"
Mémoire partagée anonyme et pas de stockage persistant
"file-name"
[DefaultRuntimeDir]/file-name
Absolute file name
$absolute-file-name
apr_status_t attach(ap_slotmem_instance_t **new, const char *name, apr_size_t *item_size, unsigned int *item_num, apr_pool_t *pool)
attache à un slot de mémoire existant. Voir create pour la description du paramètre name.
apr_status_t dptr(ap_slotmem_instance_t *s, unsigned int item_id, void**mem)
obtient la mémoire associée à ce slot actif.
apr_status_t get(ap_slotmem_instance_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len)
lit la mémoire depuis ce slot et la transfère vers dest
apr_status_t put(ap_slotmem_instance_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len)
écrit dans ce slot la mémoire en provenance de src
unsigned int num_slots(ap_slotmem_instance_t *s)
renvoie le nombre total de slots contenus dans ce segment
apr_size_t slot_size(ap_slotmem_instance_t *s)
renvoie la taille totale des données, en octets, contenues dans un slot de ce segment
apr_status_t grab(ap_slotmem_instance_t *s, unsigned int *item_id);
alloue ou s'approprie le premier slot disponible et le marque comme utilisé (n'effectue aucune copie de données)
apr_status_t fgrab(ap_slotmem_instance_t *s, unsigned int item_id);
force l'allocation ou l'attribution du slot spécifié et le marque comme utilisé (n'effectue aucune copie de données)
apr_status_t release(ap_slotmem_instance_t *s, unsigned int item_id);
libère un slot et le marque comme non utilisé (n'effectue aucune copie de données)


mod_so - Serveur Apache HTTP Version 2.4

Module Apache mod_so

Description: | Chargement de modules ou de code exécutable au cours du démarrage ou du redémarrage du serveur
Statut: | Extension
Identificateur de Module: | so_module
Fichier Source: | mod_so.c
Compatibilité: | Sous Windows, c'est un module de base (toujours inclus)

Sommaire

Sur les systèmes d'exploitation sélectionnés, ce module peut être utilisé pour charger des modules dans le serveur HTTP Apache en cours d'exécution grâce au mécanisme des Dynamic Shared Object ou Objets Partagés Dynamiquement (DSO), et évite ainsi de devoir effectuer une recompilation.

Sous Unix, le code chargé provient en général de fichiers objet partagés possèdant en général l'extension .so, alors que sous Windows, l'extension peut être soit .so, soit .dll.

Avertissement

En général, les modules compilés pour une version majeure du serveur HTTP Apache ne fonctionneront pas avec une autre (par exemple de 1.3 à 2.0 ou 2.0 à 2.2). D'une version majeure à l'autre, il y a souvent des modifications d'API qui nécessitent des modifications du module pour qu'il puisse fonctionner avec la nouvelle version.

Création de modules chargeables pour Windows

Note

Sous Windows, où les modules chargeables possèdent en général l'extension de nom de fichier .dll, les modules Apache httpd se nomment mod_nom-module.so, tout comme sur les autres plates-formes. Vous trouverez cependant encore des modules tiers, comme PHP par exemple, qui continuent d'utiliser la convention de nommage avec extension .dll.

Bien que mod_so puisse encore charger des modules possèdant un nom du style ApacheModuleFoo.dll, il est préférable d'utiliser la nouvelle convention de nommage ; si vous modifiez votre module chargeable pour la version 2.0, veuillez aussi modifier son nom pour respecter cette nouvelle convention.

Les API des modules Apache httpd sous Unix et Windows sont identiques. Alors que certains modules s'appuient sur certains aspects de l'architecture Unix non présents dans Windows, et ne fonctionneront donc pas sur cette dernière plate-forme, de nombreux modules fonctionnent sous Windows avec peu ou pas de modification par rapport à leur version Unix.

Lorsqu'un module fonctionne, il peut être ajouté au serveur de deux manières. Sous Unix, il peut être compilé dans le serveur. Comme Apache httpd pour Windows ne dispose pas du programme Configure propre à Apache httpd pour Unix, le fichier source du module doit être ajouté au fichier projet Apache de base, et ses symboles ajoutés au fichier os\win32\modules.c.

La seconde méthode consiste à compiler le module en tant que DLL, à savoir une bibliothèque partagée qui pourra être chargée dans le serveur en cours d'exécution via la directive LoadModule. Ces modules DLL peuvent être distribués et exécutés sur toute installation d'Apache httpd pour Windows, sans avoir à recompiler le serveur.

Pour créer un module DLL, il est nécessaire d'apporter une légère modification à son fichier source : l'enregistrement du module doit être exporté depuis la DLL (qui sera elle-même créée plus tard ; voir plus loin). Pour ce faire, ajoutez la macro AP_MODULE_DECLARE_DATA (définie dans les fichiers d'en-têtes d'Apache httpd) à la définition de l'enregistrement de votre module. Par exemple, si votre module est déclaré comme suit :

module foo_module;

Remplacez cette ligne par :

module AP_MODULE_DECLARE_DATA foo_module;

Notez que cette macro ne sera prise en compte que sous Windows, si bien que le module poura être utilisé sans changement sous Unix, si besoin est. Alternativement, si vous êtes familier avec les fichiers .DEF, vous pouvez les utiliser pour exporter l'enregistrement du module.

Maintenant, nous sommes prêts à créer une DLL contenant notre module. Il va falloir pour cela la lier avec la bibliothèque d'export libhttpd.lib qui a été créée au cours de la compilation de la bibliothèque partagée libhttpd.dll. Il sera peut-être aussi nécessaire de modifier la configuration du compilateur pour s'assurer que les fichiers d'en-têtes d'Apache httpd seront correctement localisés. Vous trouverez cette bibliothèque à la racine du répertoire des modules de votre serveur. Il est souhaitable d'utiliser un fichier de module .dsp existant dans l'arborescence afin de s'assurer que l'environnement de compilation est correctement configuré, mais vous pouvez aussi comparer les options de compilation et d'édition de liens à votre fichier .dsp.

Ceci devrait créer une version DLL de votre module. Il vous suffit maintenant de l'enregistrer dans le répertoire modules à la racine de votre serveur, et d'utiliser la directive LoadModule pour la charger.

Directive LoadFile

Description: | Liaison du fichier objet ou de la bibliothèque spécifié
Syntaxe: | LoadFile nom-fichier [nom-fichier] ...
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_so

La directive LoadFile permet de lier le fichier objet ou la bibliothèque spécifié au serveur lors du démarrage ou du redémarrage de ce dernier ; ceci permet d'ajouter tout code additionnel nécessaire au fonctionnement d'un module. nom-fichier est soit un chemin absolu, soit un chemin relatif au répertoire défini par la directive ServerRoot.

Par exemple :

LoadFile "libexec/libxmlparse.so"

Directive LoadModule

Description: | Liaison avec le serveur du fichier objet ou de la bibliothèque spécifié, et ajout de ce dernier à la liste des modules actifs
Syntaxe: | LoadModule module nom-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_so

La directive LoadModule permet de lier le fichier objet ou la bibliothèque nom-fichier avec le serveur, et d'ajouter la structure de module nommée module à la liste des modules actifs. module est le nom de la variable externe de type module dans le fichier, et est référencé comme Identificateur de module dans la documentation des modules.

Par exemple :

LoadModule status_module "modules/mod_status.so"

charge le module spécifié depuis le sous-répertoire des modules situé à la racine du serveur.


mod_socache_dbm - Serveur Apache HTTP Version 2.4

Module Apache mod_socache_dbm

Description: | Fournisseur de cache d'objets partagés basé sur DBM.
Statut: | Extension
Identificateur de Module: | socache_dbm_module
Fichier Source: | mod_socache_dbm.c

Sommaire

Le module mod_socache_dbm est un fournisseur de cache d'objets partagés qui permet la création et l'accès à un cache maintenu par une base de données DBM.

dbm:/chemin/vers/datafile

Vous trouverez des détails à propos des autres fournisseurs de cache d'objets partagés ici.


mod_socache_dc - Serveur Apache HTTP Version 2.4

Module Apache mod_socache_dc

Description: | Fournisseur de cache d'objets partagés basé sur dc.
Statut: | Extension
Identificateur de Module: | socache_dc_module
Fichier Source: | mod_socache_dc.c

Sommaire

Le module mod_socache_dc est un fournisseur de cache d'objets partagés qui permet la création et l'accès à un cache maintenu par les bibliothèques de mise en cache de sessions distribuées distcache.

Vous trouverez des détails à propos des autres fournisseurs de cache d'objets partagés ici.


mod_socache_memcache - Serveur Apache HTTP Version 2.4

Module Apache mod_socache_memcache

Description: | Fournisseur de cache d'objets partagés basé sur Memcache.
Statut: | Extension
Identificateur de Module: | socache_memcache_module
Fichier Source: | mod_socache_memcache.c

Sommaire

Le module mod_socache_memcache est un fournisseur de cache d'objets partagés qui permet la création et l'accès à un cache maintenu par le système de mise en cache d'objets en mémoire distribuée à hautes performances memcached.

Cette méthode "create" du fournisseur de cache d'objets partagés requiert une liste de spécifications hôte/port en cache mémoire séparées par des virgules. Si vous utilisez ce fournisseur dans la configuration d'autres modules (comme SSLSessionCache), vous devez fournir la liste des serveurs sous la forme du paramètre optionnel "arg".

SSLSessionCache memcache:memcache.example.com:12345,memcache2.example.com:12345

Vous trouverez des détails à propos des autres fournisseurs de cache d'objets partagés ici.

Directive MemcacheConnTTL

Description: | Durée de conservation des connexions inactives
Syntaxe: | MemcacheConnTTL num[units]
Défaut: | MemcacheConnTTL 15s
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_socache_memcache
Compatibilité: | Disponible à partir de la version 2.4.17 du serveur HTTP Apache.

Définit la durée pendant laquelle les connexions inactives avec le(s) serveur(s) memcache seront conservées (plateformes threadées seulement).

Les valeurs valides de la directive MemcacheConnTTL sont des durées d'une heure maximum. La valeur 0 signifie une absence de péremption

L'unité par défaut pour ce délai est la seconde, mais vous pouvez ajouter un suffixe pour spécifier une unité différente ; ms pour milliseconde, s pour seconde, min pour minute et h pour heure..

Dans les versions antérieures à 2.4.17, ce délai était codé en dur et sa valeur était 600 microsecondes. La valeur la plus proche de cette ancienne valeur pour la directive MemcacheConnTTL est donc 1ms.

# Définition d'un délai de 10 minutes
MemcacheConnTTL 10min
# Définition d'un délai de 60 secondes
MemcacheConnTTL 60


mod_socache_shmcb - Serveur Apache HTTP Version 2.4

Module Apache mod_socache_shmcb

Description: | Fournisseur de cache d'objets partagés basé sur shmcb.
Statut: | Extension
Identificateur de Module: | socache_shmcb_module
Fichier Source: | mod_socache_shmcb.c

Sommaire

Le module mod_socache_shmcb est un fournisseur de cache d'objets partagés qui permet la création et l'accès à un cache maintenu par un tampon cyclique à hautes performances au sein d'un segment de mémoire partagée.

shmcb:/chemin/vers/datafile(512000)

Vous trouverez des détails à propos des autres fournisseurs de cache d'objets partagés ici.


mod_speling - Serveur Apache HTTP Version 2.4

Module Apache mod_speling

Description: | Tente de corriger les erreurs de casse dans les URLs ou les fautes de frappe mineures.
Statut: | Extension
Identificateur de Module: | speling_module
Fichier Source: | mod_speling.c

Sommaire

Il arrive que des requêtes pour des documents ne puissent pas être traitées par le serveur Apache de base à cause d'une erreur de frappe ou de casse. Ce module permet de traiter ce problème en essayant de trouver un document correspondant, même lorsque tous les autres modules y ont renoncé. Sa méthode de travail consiste à comparer chaque nom de document du répertoire demandé avec le document de la requête sans tenir compte de la casse, et en acceptant jusqu'à une erreur (insertion, omission, inversion de caractère ou caractère erroné). Une liste de tous les documents qui correspondent est alors élaborée en utilisant cette stratégie.

Si après le parcours du répertoire,

  • aucun document correspondant n'a été trouvé, Apache procèdera normalement et renverra une erreur "document non trouvé".
  • un seul document correspondant pratiquement à la requête a été trouvé, celui-ci est renvoyé sous la forme d'une réponse de redirection.
  • plusieurs documents pouvant correspondre ont été trouvés, une liste des documents est envoyée au client afin que ce dernier puisse sélectionner le document correct.

Directive CheckCaseOnly

Description: | Limite l'action du module aux corrections de majuscules
Syntaxe: | CheckCaseOnly on|off
Défaut: | CheckCaseOnly Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Extension
Module: | mod_speling

Lorsqu'elle est définie à "on", cette directive permet de limiter l'action du module aux inversions majuscule/minuscule. Les autres corrections ne sont pas effectuées.

Directive CheckSpelling

Description: | Active le module de correction
Syntaxe: | CheckSpelling on|off
Défaut: | CheckSpelling Off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Extension
Module: | mod_speling

Cette directive permet d'activer ou de désactiver le module de correction. Lorsqu'il est activé, rappelez-vous que :

  • le parcours du répertoire nécessaire à la correction aura un impact sur les performances du serveur lorsque de nombreuses corrections devront être effectuées au même moment.
  • l'arborescence ne doit pas contenir de documents sensibles qui pourraient être considérés par erreur comme correspondant à la requête.
  • le module ne corrige pas les noms d'utilisateur mal orthographiés (comme dans http://mon.serveur/~apahce/), mais seulement les noms de fichiers ou de répertoires.
  • les corrections s'appliquent strictement aux fichiers existants, si bien qu'une requête pour <Location "/status"> pour être traitée de manière incorrecte comme une requête pour le fichier négocié "/stats.html".

mod_speling ne doit pas être activé pour des répertoires où DAV l'est aussi, car il va essayer de "corriger" les noms des ressources nouvellement créées en fonction des noms de fichiers existants ; par exemple, lors du chargement d'un nouveau document doc43.html, il est possible qu'il redirige vers un document existant doc34.html, ce qui ne correspond pas à ce que l'on souhaite.


mod_ssl - Serveur Apache HTTP Version 2.4

Module Apache mod_ssl

Description: | Chiffrement de haut niveau basé sur les protocoles Secure Sockets Layer (SSL) et Transport Layer Security (TLS)
Statut: | Extension
Identificateur de Module: | ssl_module
Fichier Source: | mod_ssl.c

Sommaire

Ce module fournit le support SSL v3 et TLS v1 au serveur HTTP Apache. SSL v2 n'est plus supporté.

Ce module s'appuie sur OpenSSL pour fournir le moteur de chiffrement.

D'autres détails, discussions et exemples sont fournis dans la documentation SSL.

Variables d'environnement

Ce module peut être configuré pour fournir aux espaces de nommage SSI et CGI de nombreux éléments d'informations concernant SSL par le biais de variables d'environnement supplémentaires. Par défaut, et pour des raisons de performances, ces informations ne sont pas fournies (Voir la directive SSLOptions StdEnvVars ci-dessous). Les variables générées se trouvent dans la table ci-dessous. Ces informations peuvent également être disponible sous des noms différents à des fins de compatibilité ascendante. Reportez-vous au chapitre Compatibilité pour plus de détails à propos des variables de compatibilité.

Nom de la variable : | Type de valeur : | Description :
HTTPS | drapeau | HTTPS est utilisé.
SSL_PROTOCOL | chaîne | La version du protocole SSL (SSLv3, TLSv1, TLSv1.1, TLSv1.2)
SSL_SESSION_ID | chaîne | L'identifiant de session SSL codé en hexadécimal
SSL_SESSION_RESUMED | chaîne | Session SSL initiale ou reprise. Note : plusieurs requêtes peuvent être servies dans le cadre de la même session SSL (initiale ou reprise) si les connexions persistantes (HTTP KeepAlive) sont utilisées
SSL_SECURE_RENEG | chaîne | true si la renégociation sécurisée est supportée, false dans le cas contraire
SSL_CIPHER | chaîne | Le nom de l'algorithme de chiffrement
SSL_CIPHER_EXPORT | chaîne | true si l'algorithme de chiffrement est un algorithme exporté
SSL_CIPHER_USEKEYSIZE | nombre | Nombre de bits de chiffrement (réellement utilisés)
SSL_CIPHER_ALGKEYSIZE | nombre | Nombre de bits de chiffrement (possible)
SSL_COMPRESS_METHOD | chaîne | Méthode de compression SSL négociée
SSL_VERSION_INTERFACE | chaîne | La version du programme mod_ssl
SSL_VERSION_LIBRARY | chaîne | La version du programme OpenSSL
SSL_CLIENT_M_VERSION | chaîne | La version du certificat client
SSL_CLIENT_M_SERIAL | chaîne | Le numéro de série du certificat client
SSL_CLIENT_S_DN | chaîne | Le DN sujet du certificat client
SSL_CLIENT_S_DN_x509 | chaîne | Elément du DN sujet du client
SSL_CLIENT_SAN_Email_n | chaîne | Les entrées d'extension subjectAltName du certificat client de type rfc822Name
SSL_CLIENT_SAN_DNS_n | chaîne | Les entrées d'extension subjectAltName du certificat client de type dNSName
SSL_CLIENT_SAN_OTHER_msUPN_n | chaîne | Extensions subjectAltName de type otherName du certificat client, forme Microsoft du nom principal de l'utilisateur (OID 1.3.6.1.4.1.311.20.2.3)
SSL_CLIENT_I_DN | chaîne | DN de l'émetteur du certificat du client
SSL_CLIENT_I_DN_x509 | chaîne | Elément du DN de l'émetteur du certificat du client
SSL_CLIENT_V_START | chaîne | Validité du certificat du client (date de début)
SSL_CLIENT_V_END | chaîne | Validité du certificat du client (date de fin)
SSL_CLIENT_V_REMAIN | chaîne | Nombre de jours avant expiration du certificat du client
SSL_CLIENT_A_SIG | chaîne | Algorithme utilisé pour la signature du certificat du client
SSL_CLIENT_A_KEY | chaîne | Algorithme utilisé pour la clé publique du certificat du client
SSL_CLIENT_CERT | chaîne | Certificat du client au format PEM
SSL_CLIENT_CERT_CHAIN_n | chaîne | Certificats de la chaîne de certification du client au format PEM
SSL_CLIENT_CERT_RFC4523_CEA | chaîne | Numéro de série et fournisseur du certificat. le format correspond à celui de la CertificateExactAssertion dans la RFC4523
SSL_CLIENT_VERIFY | chaîne | NONE, SUCCESS, GENEROUS ou FAILED:raison
SSL_SERVER_M_VERSION | chaîne | La version du certificat du serveur
SSL_SERVER_M_SERIAL | chaîne | The serial of the server certificate
SSL_SERVER_S_DN | chaîne | DN sujet du certificat du serveur
SSL_SERVER_S_DN_x509 | chaîne | Elément du DN sujet du certificat du serveur
SSL_SERVER_SAN_Email_n | chaîne | Les entrées d'extension subjectAltName du certificat de serveur de type rfc822Name
SSL_SERVER_SAN_DNS_n | chaîne | Les entrées d'extension subjectAltName du certificat de serveur de type dNSName
SSL_SERVER_SAN_OTHER_dnsSRV_n | chaîne | Extensions subjectAltName de type otherName du certificat serveur, sous la forme SRVName (OID 1.3.6.1.5.5.7.8.7, RFC 4985)
SSL_SERVER_I_DN | chaîne | DN de l'émetteur du certificat du serveur
SSL_SERVER_I_DN_x509 | chaîne | Elément du DN de l'émetteur du certificat du serveur
SSL_SERVER_V_START | chaîne | Validité du certificat du serveur (date de dédut)
SSL_SERVER_V_END | chaîne | Validité du certificat du serveur (date de fin)
SSL_SERVER_A_SIG | chaîne | Algorithme utilisé pour la signature du certificat du serveur
SSL_SERVER_A_KEY | chaîne | Algorithme utilisé pour la clé publique du certificat du serveur
SSL_SERVER_CERT | chaîne | Certificat du serveur au format PEM
SSL_SRP_USER | chaîne | nom d'utilisateur SRP
SSL_SRP_USERINFO | chaîne | informations sur l'utilisateur SRP
SSL_TLS_SNI | string | Contenu de l'extension SNI TLS (si supporté par ClientHello)

x509 spécifie un élément de DN X.509 parmi C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email. A partir de la version 2.2.0 d'Apache, x509 peut aussi comporter un suffixe numérique _n. Si le DN en question comporte plusieurs attributs de noms identiques, ce suffixe constitue un index débutant à zéro et permettant de sélectionner un attribut particulier. Par exemple, si le DN sujet du certificat du serveur comporte deux champs OU, on peut utiliser SSL_SERVER_S_DN_OU_0 et SSL_SERVER_S_DN_OU_1 pour référencer chacun d'entre eux. Un nom de variable sans suffixe _n est équivalent au même nom avec le suffixe _0, ce qui correspond au premier attribut (ou au seul) caractérisant le DN. Lorsque la table d'environnement est remplie en utilisant l'option StdEnvVars de la directive SSLOptions, le premier attribut (ou le seul) caractérisant le DN est enregistré avec un nom sans suffixe ; autrement dit, aucune entrée possédant comme suffixe _0 n'est enregistrée.

A partir de la version 2.4.32 de httpd, on peut ajouter le suffixe _RAW à x509 dans un composant DN afin d'empêcher la conversion de la valeur de l'attribut en UTF-8. Il doit être placé après le suffixe index (s'il existe). On utilisera par exemple SSL_SERVER_S_DN_OU_RAW ou SSL_SERVER_S_DN_OU_0_RAW.

Le format des variables *_DN a changé depuis la version 2.3.11 d'Apache HTTPD. Voir l'option LegacyDNStringFormat de la directive SSLOptions pour plus de détails.

SSL_CLIENT_V_REMAIN n'est disponible qu'à partir de la version 2.1.

Plusieurs variables d'environnement additionnelles peuvent être utilisées dans les expressions SSLRequire, ou dans les formats de journalisation personnalisés :

HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE
HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE
HTTP_COOKIE            REMOTE_HOST           API_VERSION
HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR
HTTP_HOST              IS_SUBREQ             TIME_MON
HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY
HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR
THE_REQUEST            SERVER_NAME           TIME_MIN
REQUEST_FILENAME       SERVER_PORT           TIME_SEC
REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
REQUEST_SCHEME         REMOTE_ADDR           TIME
REQUEST_URI            REMOTE_USER

Dans ces contextes, deux formats spéciaux peuvent aussi être utilisés :

ENV:nom_variable
Correspond à la variable d'environnement standard nom_variable.
HTTP:nom_en-tête
Correspond à la valeur de l'en-tête de requête dont le nom est nom_en-tête.

Formats de journaux personnalisés

Lorsque mod_ssl est compilé dans le serveur Apache ou même chargé (en mode DSO), des fonctions supplémentaires sont disponibles pour le Format de journal personnalisé du module mod_log_config. A ce titre, la fonction de format d'eXtension ``%{nom-var}x'' peut être utilisée pour présenter en extension toute variable fournie par tout module, et en particulier celles fournies par mod_ssl et que vous trouverez dans la table ci-dessus.

A des fins de compatibilité ascendante, il existe une fonction de format cryptographique supplémentaire ``%{nom}c''. Vous trouverez toutes les informations à propos de cette fonction dans le chapitre Compatibilité.

Exemple

CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Ces formats sont disponibles même si l'option StdEnvVars de la directive SSLOptions n'a pas été définie.

Information à propos de la requête

mod_ssl enregistre des informations à propos de la requête que l'on peut restituer dans les journaux avec la chaîne de format %{nom}n via le module mod_log_config.

Les informations enregistrées sont les suivantes :

ssl-access-forbidden
Cette information contient la valeur 1 si l'accès a été refusé suite à une directive SSLRequire ou SSLRequireSSL.
ssl-secure-reneg
Si mod_ssl a été compilé avec une version d'OpenSSL qui supporte la renégociation sécurisée, si SSL est utilisé pour la connexion courante et si le client supporte lui aussi la renégociation sécurisée, cette information contiendra la valeur 1. Si le client ne supporte pas la renégociation sécurisée, l'information contiendra la valeur 0. Si mod_ssl n'a pas été compilé avec une version d'OpenSSL qui supporte la renégociation sécurisée, ou si SSL n'est pas utilisé pour la connexion courante, le contenu de l'information ne sera pas défini.

Extension pour l'interprétation des expressions

Lorsque mod_ssl est compilé statiquement avec Apache, ou même chargé dynamiquement (en tant que module DSO), toute variable en provenance de mod_ssl peut être utilisée pour l'interprétation des expression ap_expr. Les variables peuvent être référencées en utilisant la syntaxe ``%{varname}''. A partir de la version 2.4.18, on peut aussi utiliser la syntaxe de style mod_rewrite ``%{SSL:varname}'', ou la syntaxe de style fonction ``ssl(varname)''.

Exemple (en utilisant mod_headers)

Header set X-SSL-PROTOCOL "expr=%{SSL_PROTOCOL}"
Header set X-SSL-CIPHER "expr=%{SSL:SSL_CIPHER}"

Cette fonctionnalité est disponible même si l'option StdEnvVars de la directive SSLOptions n'a pas été définie.

Fournisseurs d'autorisation disponibles avec Require

mod_ssl propose quelques fournisseurs d'autorisation à utiliser avec la directive Require du module mod_authz_core.

Require ssl

Le fournisseur ssl refuse l'accès si une connexion n'est pas chiffrée avec SSL. L'effet est similaire à celui de la directive SSLRequireSSL.

Require ssl

Require ssl-verify-client

Le fournisseur ssl autorise l'accès si l'utilisateur est authentifié via un certificat client valide. Ceci n'a un effet que si SSLVerifyClient optional est actif.

Dans l'exemple suivant, l'accès est autorisé si le client est authentifié via un certificat client ou par nom d'utilisateur/mot de passe :

Require ssl-verify-client
Require valid-user

Directive SSLCACertificateFile

Description: | Fichier contenant une concaténation des certificats de CA codés en PEM pour l'authentification des clients
Syntaxe: | SSLCACertificateFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier tout-en-un où vous pouvez rassembler les certificats des Autorités de Certification (CAs) pour les clients auxquels vous avez à faire. On les utilise pour l'authentification des clients. Un tel fichier contient la simple concaténation des différents fichiers de certificats codés en PEM, par ordre de préférence. Cette directive peut être utilisée à la place et/ou en complément de la directive SSLCACertificatePath.

Exemple

SSLCACertificateFile "/usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt"

Directive SSLCACertificatePath

Description: | Répertoire des certificats de CA codés en PEM pour l'authentification des clients
Syntaxe: | SSLCACertificatePath chemin-répertoire
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le répertoire où sont stockés les certificats des Autorités de Certification (CAs) pour les clients auxquels vous avez à faire. On les utilise pour vérifier le certificat du client au cours de l'authentification de ce dernier.

Les fichiers de ce répertoire doivent être codés en PEM et ils sont accédés via des noms de fichier sous forme de condensés ou hash. Il ne suffit donc pas de placer les fichiers de certificats dans ce répertoire : vous devez aussi créer des liens symboliques nommés valeur-de-hashage.N, et vous devez toujours vous assurer que ce répertoire contient les liens symboliques appropriés.

Exemple

SSLCACertificatePath "/usr/local/apache2/conf/ssl.crt/"

Directive SSLCADNRequestFile

Description: | Fichier contenant la concaténation des certificats de CA codés en PEM pour la définition de noms de CA acceptables
Syntaxe: | SSLCADNRequestFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Lorsque mod_ssl demande un certificat client, une liste de noms d'Autorités de Certification acceptables est envoyée au client au cours de la phase d'initialisation de la connexion SSL. Le client peut alors utiliser cette liste de noms de CA pour sélectionner un certificat client approprié parmi ceux dont il dispose.

Si aucune des directives SSLCADNRequestPath ou SSLCADNRequestFile n'est définie, la liste de noms de CsA acceptables envoyée au client est la liste des noms de tous les certificats de CA spécifiés par les directives SSLCACertificateFile et SSLCACertificatePath ; en d'autres termes, c'est la liste des noms de CAs qui sera effectivement utilisée pour vérifier le certificat du client.

Dans certaines situations, il est utile de pouvoir envoyer une liste de noms de CA acceptables qui diffère de la liste des CAs effectivement utilisés pour vérifier le certificat du client ; considérons par exemple le cas où le certificat du client est signé par des CAs intermédiaires. On peut ici utiliser les directives SSLCADNRequestPath et/ou SSLCADNRequestFile, et les noms de CA acceptables seront alors extraits de l'ensemble des certificats contenus dans le répertoire et/ou le fichier définis par cette paire de directives.

SSLCADNRequestFile doit spécifier un fichier tout-en-un contenant une concaténation des certificats de CA codés en PEM.

Exemple

SSLCADNRequestFile "/usr/local/apache2/conf/ca-names.crt"

Directive SSLCADNRequestPath

Description: | Répertoire contenant des fichiers de certificats de CA codés en PEM pour la définition de noms de CA acceptables
Syntaxe: | SSLCADNRequestPath chemin-répertoire
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive optionnelle permet de définir la liste de noms de CAs acceptables qui sera envoyée au client lorsqu'un certificat de client est demandé. Voir la directive SSLCADNRequestFile pour plus de détails.

Les fichiers de ce répertoire doivent être codés en PEM et ils sont accédés via des noms de fichier sous forme de condensés ou hash. Il ne suffit donc pas de placer les fichiers de certificats dans ce répertoire : vous devez aussi créer des liens symboliques nommés valeur-de-hashage.N, et vous devez toujours vous assurer que ce répertoire contient les liens symboliques appropriés.

Exemple

SSLCADNRequestPath "/usr/local/apache2/conf/ca-names.crt/"

Directive SSLCARevocationCheck

Description: | Active la vérification des révocations basée sur les CRL
Syntaxe: | SSLCARevocationCheck chain|leaf|none flags
Défaut: | SSLCARevocationCheck none
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Le drapeau optionnel flags est disponible à partir de la version 2.4.21 du serveur HTTP Apache

Active la vérification des révocations basée sur les Listes de Révocations de Certificats (CRL). Au moins une des directives SSLCARevocationFile ou SSLCARevocationPath doit être définie. Lorsque cette directive est définie à chain (valeur recommandée), les vérifications CRL sont effectuées sur tous les certificats de la chaîne, alors que la valeur leaf limite la vérification au certificat hors chaîne (la feuille).

flags peut prendre comme valeurs

  • no_crl_for_cert_ok

    Avant la version 2.3.15, les vérifications CRL dans mod_ssl réussissaient même si aucune CRL n'était trouvée dans les chemins définis par les directives SSLCARevocationFile ou SSLCARevocationPath.

    Le comportement a changé avec l'introduction de la directive SSLCARevocationFile : par défaut avec chain ou leaf, les CRLs doivent être présentes pour que la validation réussisse ; dans le cas contraire, elle échouera avec une erreur "unable to get certificate CRL".

    La valeur no_crl_for_cert_ok du drapeau flag permet de retrouver le comportement précédent.

Exemple

SSLCARevocationCheck chain

Compatibilité avec la branche 2.2

SSLCARevocationCheck chain no_crl_for_cert_ok

Directive SSLCARevocationFile

Description: | Fichier contenant la concaténation des CRLs des CA codés en PEM pour l'authentification des clients
Syntaxe: | SSLCARevocationFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier tout-en-un où sont rassemblées les Listes de Révocation de Certificats (CRLs) des Autorités de certification (CAs) pour les clients auxquels vous avez à faire. On les utilise pour l'authentification des clients. Un tel fichier contient la simple concaténation des différents fichiers de CRLs codés en PEM, dans l'ordre de préférence. Cette directive peut être utilisée à la place et/ou en complément de la directive SSLCARevocationPath.

Exemple

SSLCARevocationFile
"/usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl"

Directive SSLCARevocationPath

Description: | Répertoire des CRLs de CA codés en PEM pour l'authentification des clients
Syntaxe: | SSLCARevocationPath chemin-répertoire
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le répertoire où sont stockées les Listes de Révocation de Certificats (CRL) des Autorités de Certification (CAs) pour les clients auxquels vous avez à faire. On les utilise pour révoquer les certificats des clients au cours de l'authentification de ces derniers.

Les fichiers de ce répertoire doivent être codés en PEM et ils sont accédés via des noms de fichier sous forme de condensés ou hash. Il ne suffit donc pas de placer les fichiers de CRL dans ce répertoire : vous devez aussi créer des liens symboliques nommés valeur-de-hashage.N, et vous devez toujours vous assurer que ce répertoire contient les liens symboliques appropriés.

Exemple

SSLCARevocationPath "/usr/local/apache2/conf/ssl.crl/"

Directive SSLCertificateChainFile

Description: | Fichier contenant les certificats de CA du serveur codés en PEM
Syntaxe: | SSLCertificateChainFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

SSLCertificateChainFile est obsolète

SSLCertificateChainFile est devenue obsolète avec la version 2.4.8, lorsque la directive SSLCertificateFile a été étendue pour supporter aussi les certificats de CA intermédiaires dans le fichier de certificats du serveur.

Cette directive permet de définir le fichier optionnel tout-en-un où vous pouvez rassembler les certificats des Autorités de Certification (CA) qui forment la chaîne de certification du certificat du serveur. Cette chaîne débute par le certificat de la CA qui a délivré le certificat du serveur et peut remonter jusqu'au certificat de la CA racine. Un tel fichier contient la simple concaténation des différents certificats de CA codés en PEM, en général dans l'ordre de la chaîne de certification.

Elle doit être utilisée à la place et/ou en complément de la directive SSLCACertificatePath pour construire explicitement la chaîne de certification du serveur qui est envoyée au navigateur en plus du certificat du serveur. Elle s'avère particulièrement utile pour éviter les conflits avec les certificats de CA lorsqu'on utilise l'authentification du client. Comme le fait de placer un certificat de CA de la chaîne de certification du serveur dans la directive SSLCACertificatePath produit le même effet pour la construction de la chaîne de certification, cette directive a pour effet colatéral de faire accepter les certificats clients fournis par cette même CA, au cours de l'authentification du client.

Soyez cependant prudent : fournir la chaîne de certification ne fonctionne que si vous utilisez un simple certificat de serveur RSA ou DSA. Si vous utilisez une paire de certificats couplés RSA+DSA , cela ne fonctionnera que si les deux certificats utilisent vraiment la même chaîne de certification. Dans le cas contraire, la confusion risque de s'installer au niveau des navigateurs.

Exemple

SSLCertificateChainFile "/usr/local/apache2/conf/ssl.crt/ca.crt"

Directive SSLCertificateFile

Description: | Fichier de données contenant le certificat X.509 du serveur codé en PEM
Syntaxe: | SSLCertificateFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier de données contenant les informations de certificat X.509 du serveur codées au format PEM. Ce fichier doit contenir au minimum un certificat d'entité finale (feuille). La directive peut être utilisée plusieurs fois (elle référence des fichiers différents) pour accepter plusieurs algorithmes d'authentification au niveau du serveur - souvent RSA, DSA et ECC. Le nombre d'algorithmes supportés dépend de la version d'OpenSSL utilisée avec mod_ssl : à partir de la version 1.0.0, la commande openssl list-public-key-algorithms affiche la liste des algorithmes supportés. Voir aussi la note ci-dessous à propos des limitations des versions d'OpenSSL antérieures à 1.0.2 et la manière de les contourner.

Les fichiers peuvent aussi contenir des certificats de CA intermédiaires triés depuis la feuille vers la racine. Cette fonctionnalité est disponible depuis la version 2.4.8 du serveur HTTP Apache, et rend obsolète la directive SSLCertificateChainFile. A partir de la version 1.0.2 d'OpenSSL, il est alors possible de configurer la chaîne de certification en fonction du certificat.

Depuis la version 2.4.7 du serveur HTTP Apache, on peut aussi ajouter des paramètres DH personnalisés et un nom EC curve pour les clés éphémères à la fin du premier fichier défini par la directive SSLCertificateFile. Ces paramètres peuvent être générés avec les commandes openssl dhparam et openssl ecparam, et ils peuvent être ajoutés tel quel à la fin du premier fichier de certificat. En effet, seul le premier fichier de certificat défini peut être utilisé pour enregistrer des paramètres personnalisés, car ces derniers s'appliquent indépendamment de l'algorithme d'authentification utilisé.

Enfin, il est aussi possible d'ajouter la clé privée du certificat de l'entité finale au fichier de certificat, ce qui permet de se passer d'une directive SSLCertificateKeyFile séparée. Cette pratique est cependant fortement déconseillée. En effet, les fichiers de certificats qui contiennent de tels clés embarquées doivent être définis avant les certificats en utilisant un fichier de clé séparé. En outre, si la clé est chiffrée, une boîte de dialogue pour entrer le mot de passe de la clé s'ouvre au démarrage du serveur.

Interopérabilité des paramètres DH avec les nombres premiers de plus de 1024 bits

Depuis la version 2.4.7, mod_ssl utilise des paramètres DH standardisés avec des nombres premiers de 2048, 3072 et 4096 bits, et avec des nombres premiers de 6144 et 8192 bits depuis la version 2.4.10 (voir RFC 3526), et les fournit aux clients en fonction de la longueur de la clé du certificat RSA/DSA. En particulier avec les clients basés sur Java (versions 7 et antérieures), ceci peut provoquer des erreurs au cours de la négociation - voir cette réponse de la FAQ SSL pour contourner les problèmes de ce genre.

Paramètres DH par défaut lorsqu'on utilise plusieurs certificats et une version d'OpenSSL antérieure à 1.0.2.

Lorsqu'on utilise plusieurs certificats pour supporter différents algorithmes d'authentification (comme RSA, DSA, mais principalement ECC) et une version d'OpenSSL antérieure à 1.0.2, il est recommandé soit d'utiliser des paramètres DH spécifiques (solution à privilégier) en les ajoutant au premier fichier certificat (comme décrit ci-dessus), soit d'ordonner les directives SSLCertificateFile de façon à ce que les certificats RSA/DSA soit placés après les certificats ECC.

Cette limitation est présente dans les anciennes versions d'OpenSSL qui présentent toujours le dernier certificat configuré, au lieu de laisser le serveur HTTP Apache déterminer le certificat sélectionné lors de la phase de négociation de la connexion (lorsque les paramètres DH doivent être envoyés à l'hôte distant). De ce fait, le serveur peut sélectionner des paramètres DH par défaut basés sur la longueur de la clé du mauvais certificat (les clés ECC sont beaucoup plus petites que les clés RSA/DSA et leur longueur n'est pas pertinente pour la sélection des nombres premiers DH).

Ce problème peut être résolu en créant et configurant des paramètres DH spécifiques (comme décrit ci-dessus), car ils l'emportent toujours sur les paramètres DH par défaut, et vous pourrez ainsi utiliser une longueur spécifique et appropriée.

Exemple

SSLCertificateFile "/usr/local/apache2/conf/ssl.crt/server.crt"

Directive SSLCertificateKeyFile

Description: | Fichier contenant la clé privée du serveur codée en PEM
Syntaxe: | SSLCertificateKeyFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier contenant la clé privée du serveur codée en PEM. Si la clé privée est chiffrée, une boîte de dialogue demandant le mot de passe s'ouvre au démarrage.

Cette directive peut être utilisée plusieurs fois pour référencer différents noms de fichiers, afin de supporter plusieurs algorithmes pour l'authentification du serveur. A chaque directive SSLCertificateKeyFile doit être associée une directive SSLCertificateFile correspondante.

La clé privé peut aussi être ajoutée au fichier défini par la directive SSLCertificateFile, mais cette pratique est fortement déconseillée. En effet, les fichiers de certificats qui comportent une telle clé doivent être définis après les certificats en utilisant un fichier de clé séparé.

Exemple

SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key"

Directive SSLCipherSuite

Description: | Algorithmes de chiffrement disponibles pour la négociation au cours de l'initialisation de la connexion SSL
Syntaxe: | SSLCipherSuite algorithmes
Défaut: | SSLCipherSuite DEFAULT (dépend de la version d'OpenSSL installée)
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ssl

Cette directive complexe utilise la chaîne algorithmes contenant la liste des algorithmes de chiffrement OpenSSL que le client peut utiliser au cours de la phase d'initialisation de la connexion SSL. Notez que cette directive peut être utilisée aussi bien dans un contexte de serveur que dans un contexte de répertoire. Dans un contexte de serveur, elle s'applique à l'initialisation SSL standard lorsqu'une connexion est établie. Dans un contexte de répertoire, elle force une renégociation SSL avec la liste d'algorithmes de chiffrement spécifiée après la lecture d'une requête HTTP, mais avant l'envoi de la réponse HTTP.

La liste d'algorithmes de chiffrement SSL spécifiée par l'argument algorithmes comporte quatre attributs principaux auxquels s'ajoutent quelques attributs secondaires :

  • Algorithme d'échange de clés:
    RSA, Diffie-Hellman, Elliptic Curve Diffie-Hellman, Secure Remote Password
  • Algorithme d'authentification:
    RSA, Diffie-Hellman, DSS, ECDSA ou none.
  • Algorithme de chiffrement:
    AES, DES, Triple-DES, RC4, RC2, IDEA, etc...
  • Algorithme de condensé MAC:
    MD5, SHA or SHA1, SHA256, SHA384.

L'algorithme de chiffrement peut aussi provenir de l'extérieur. Les algorithmes SSLv2 ne sont plus supportés. Pour définir les algorithmes à utiliser, on peut soit spécifier tous les algorithmes à la fois, soit utiliser des alias pour spécifier une liste d'algorithmes dans leur ordre de préférence (voir Table 1). Les algorithmes et alias effectivement disponibles dépendent de la version d'openssl utilisée. Les versions ultérieures d'openssl inclueront probablement des algorithmes supplémentaires.

Symbole | Description
Algorithme d'échange de clés :
kRSA | Echange de clés RSA
kDHr | Echange de clés Diffie-Hellman avec clé RSA
kDHd | Echange de clés Diffie-Hellman avec clé DSA
kEDH | Echange de clés Diffie-Hellman temporaires (pas de certificat)
kSRP | échange de clés avec mot de passe distant sécurisé (SRP)
Algorithmes d'authentification :
aNULL | Pas d'authentification
aRSA | Authentification RSA
aDSS | Authentification DSS
aDH | Authentification Diffie-Hellman
Algorithmes de chiffrement :
eNULL | Pas de chiffrement
NULL | alias pour eNULL
AES | Chiffrement AES
DES | Chiffrement DES
3DES | Chiffrement Triple-DES
RC4 | Chiffrement RC4
RC2 | Chiffrement RC2
IDEA | Chiffrement IDEA
Algorithmes de condensés MAC :
MD5 | Fonction de hashage MD5
SHA1 | Fonction de hashage SHA1
SHA | alias pour SHA1
SHA256 | >Fonction de hashage SHA256
SHA384 | >Fonction de hashage SHA384
Alias :
SSLv3 | tous les algorithmes de chiffrement SSL version 3.0
TLSv1 | tous les algorithmes de chiffrement TLS version 1.0
EXP | tous les algorithmes de chiffrement externes
EXPORT40 | tous les algorithmes de chiffrement externes limités à 40 bits
EXPORT56 | tous les algorithmes de chiffrement externes limités à 56 bits
LOW | tous les algorithmes de chiffrement faibles (non externes, DES simple)
MEDIUM | tous les algorithmes avec chiffrement 128 bits
HIGH | tous les algorithmes utilisant Triple-DES
RSA | tous les algorithmes utilisant l'échange de clés RSA
DH | tous les algorithmes utilisant l'échange de clés Diffie-Hellman
EDH | tous les algorithmes utilisant l'échange de clés Diffie-Hellman temporaires
ECDH | échange de clés Elliptic Curve Diffie-Hellman
ADH | tous les algorithmes utilisant l'échange de clés Diffie-Hellman anonymes
AECDH | tous les algorithmes utilisant l'échange de clés Elliptic Curve Diffie-Hellman
SRP | tous les algorithmes utilisant l'échange de clés avec mot de passe distant sécurisé (SRP)
DSS | tous les algorithmes utilisant l'authentification DSS
ECDSA | tous les algorithmes utilisant l'authentification ECDSA
aNULL | tous les algorithmes n'utilisant aucune authentification

Cela devient intéressant lorsque tous ces symboles sont combinés ensemble pour spécifier les algorithmes disponibles et l'ordre dans lequel vous voulez les utiliser. Pour simplifier tout cela, vous disposez aussi d'alias (SSLv3, TLSv1, EXP, LOW, MEDIUM, HIGH) pour certains groupes d'algorithmes. Ces symboles peuvent être reliés par des préfixes pour former la chaîne algorithmes. Les préfixes disponibles sont :

  • none: ajoute l'algorithme à la liste
  • +: déplace les algorithmes qui conviennent à la place courante dans la liste
  • -: supprime l'algorithme de la liste (peut être rajouté plus tard)
  • !: supprime définitivement l'algorithme de la liste (ne peut plus y être rajouté plus tard)

Les algorithmes aNULL, eNULL et EXP sont toujours désactivés

Depuis la version 2.4.7, les algorithmes de type null ou destinés à l'exportation sont toujours désactivés car mod_ssl ajoute obligatoirement !aNULL:!eNULL:!EXP à toute chaîne d'algorithme de chiffrement à l'initialisation.

Pour vous simplifier la vie, vous pouvez utiliser la commande ``openssl ciphers -v'' qui vous fournit un moyen simple de créer la chaîne algorithmes avec succès. La chaîne algorithmes par défaut dépend de la version des bibliothèques SSL installées. Supposons qu'elle contienne ``RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5'', ce qui stipule de mettre RC4-SHA et AES128-SHA en premiers, car ces algorithmes présentent un bon compromis entre vitesse et sécurité. Viennent ensuite les algorithmes de sécurité élevée et moyenne. En fin de compte, les algorithmes qui n'offrent aucune authentification sont exclus, comme les algorithmes anonymes Diffie-Hellman pour SSL, ainsi que tous les algorithmes qui utilisent MD5 pour le hashage, car celui-ci est reconnu comme insuffisant.

$ openssl ciphers -v 'RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5'
RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
AES128-SHA              SSLv3 Kx=RSA      Au=RSA  Enc=AES(128)  Mac=SHA1
DHE-RSA-AES256-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(256)  Mac=SHA1
...                     ...               ...     ...           ...
SEED-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=SEED(128) Mac=SHA1
PSK-RC4-SHA             SSLv3 Kx=PSK      Au=PSK  Enc=RC4(128)  Mac=SHA1
KRB5-RC4-SHA            SSLv3 Kx=KRB5     Au=KRB5 Enc=RC4(128)  Mac=SHA1

Vous trouverez la liste complète des algorithmes RSA & DH spécifiques à SSL dans la Table 2.

Exemple

SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
Symbole algorithme | Protocole | Echange de clés | Authentification | Chiffrement | Condensé MAC | Type
Algorithmes RSA :
DES-CBC3-SHA | SSLv3 | RSA | RSA | 3DES(168) | SHA1 |
IDEA-CBC-SHA | SSLv3 | RSA | RSA | IDEA(128) | SHA1 |
RC4-SHA | SSLv3 | RSA | RSA | RC4(128) | SHA1 |
RC4-MD5 | SSLv3 | RSA | RSA | RC4(128) | MD5 |
DES-CBC-SHA | SSLv3 | RSA | RSA | DES(56) | SHA1 |
EXP-DES-CBC-SHA | SSLv3 | RSA(512) | RSA | DES(40) | SHA1 | export
EXP-RC2-CBC-MD5 | SSLv3 | RSA(512) | RSA | RC2(40) | MD5 | export
EXP-RC4-MD5 | SSLv3 | RSA(512) | RSA | RC4(40) | MD5 | export
NULL-SHA | SSLv3 | RSA | RSA | None | SHA1 |
NULL-MD5 | SSLv3 | RSA | RSA | None | MD5 |
Algorithmes Diffie-Hellman :
ADH-DES-CBC3-SHA | SSLv3 | DH | None | 3DES(168) | SHA1 |
ADH-DES-CBC-SHA | SSLv3 | DH | None | DES(56) | SHA1 |
ADH-RC4-MD5 | SSLv3 | DH | None | RC4(128) | MD5 |
EDH-RSA-DES-CBC3-SHA | SSLv3 | DH | RSA | 3DES(168) | SHA1 |
EDH-DSS-DES-CBC3-SHA | SSLv3 | DH | DSS | 3DES(168) | SHA1 |
EDH-RSA-DES-CBC-SHA | SSLv3 | DH | RSA | DES(56) | SHA1 |
EDH-DSS-DES-CBC-SHA | SSLv3 | DH | DSS | DES(56) | SHA1 |
EXP-EDH-RSA-DES-CBC-SHA | SSLv3 | DH(512) | RSA | DES(40) | SHA1 | export
EXP-EDH-DSS-DES-CBC-SHA | SSLv3 | DH(512) | DSS | DES(40) | SHA1 | export
EXP-ADH-DES-CBC-SHA | SSLv3 | DH(512) | None | DES(40) | SHA1 | export
EXP-ADH-RC4-MD5 | SSLv3 | DH(512) | None | RC4(40) | MD5 | export

Directive SSLCompression

Description: | Permet d'activer la compression au niveau SSL
Syntaxe: | SSLCompression on|off
Défaut: | SSLCompression off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible à partir de la version 2.4.3 du serveur HTTP Apache, si on utilise une version d'OpenSSL 0.9.8 ou supérieure ; l'utilisation dans un contexte de serveur virtuel n'est disponible que si on utilise une version d'OpenSSL 1.0.0 ou supérieure. La valeur par défaut était on dans la version 2.4.3.

Cette directive permet d'activer la compression au niveau SSL.

L'activation de la compression est à l'origine de problèmes de sécurité dans la plupart des configurations (l'attaque nommée CRIME).

Directive SSLCryptoDevice

Description: | Active l'utilisation d'un accélérateur matériel de chiffrement
Syntaxe: | SSLCryptoDevice moteur
Défaut: | SSLCryptoDevice builtin
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ssl

Cette directive permet d'activer l'utilisation d'une carte accélératrice de chiffrement qui prendra en compte certaines parties du traitement relatif à SSL. Cette directive n'est utilisable que si la boîte à outils SSL à été compilée avec le support "engine" ; les versions 0.9.7 et supérieures d'OpenSSL possèdent par défaut le support "engine", alors qu'avec la version 0.9.6, il faut utiliser les distributions séparées "-engine".

Pour déterminer les moteurs supportés, exécutez la commande "openssl engine".

Exemple

# Pour un accélérateur Broadcom :
SSLCryptoDevice ubsec

Directive SSLEngine

Description: | Interrupteur marche/arrêt du moteur SSL
Syntaxe: | SSLEngine on|off|optional
Défaut: | SSLEngine off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet d'activer/désactiver le moteur du protocole SSL/TLS. Elle doit être utilisée dans une section <VirtualHost> pour activer SSL/TLS pour ce serveur virtuel particulier. Par défaut, le moteur du protocole SSL/TLS est désactivé pour le serveur principal et tous les serveurs virtuels configurés.

Exemple

<VirtualHost _default_:443>
SSLEngine on
#...
</VirtualHost>

Depuis la version 2.1 d'Apache, la directive SSLEngine peut être définie à optional, ce qui active le support de RFC 2817, Upgrading to TLS Within HTTP/1.1. Pour le moment, aucun navigateur web ne supporte RFC 2817.

Directive SSLFIPS

Description: | Coimmutateur du mode SSL FIPS
Syntaxe: | SSLFIPS on|off
Défaut: | SSLFIPS off
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ssl

Cette directive permet d'activer/désactiver l'utilisation du drapeau FIPS_mode de la bibliothèque SSL. Elle doit être définie dans le contexte du serveur principal, et n'accepte pas les configurations sources de conflits (SSLFIPS on suivi de SSLFIPS off par exemple). Le mode s'applique à toutes les opérations de la bibliothèque SSL.

Si httpd a été compilé avec une bibliothèque SSL qui ne supporte pas le drapeau FIPS_mode, la directive SSLFIPS on échouera. Reportez-vous au document sur la politique de sécurité FIPS 140-2 de la bibliothèque du fournisseur SSL, pour les prérequis spécifiques nécessaires à l'utilisation de mod_ssl selon un mode d'opération approuvé par FIPS 140-2 ; notez que mod_ssl en lui-même n'est pas validé, mais peut être décrit comme utilisant un module de chiffrement validé par FIPS 140-2, lorsque tous les composants sont assemblés et mis en oeuvre selon les recommandations de la politique de sécurité applicable.

Directive SSLHonorCipherOrder

Description: | Option permettant de classer les algorithmes de chiffrement du serveur par ordre de préférence
Syntaxe: | SSLHonorCipherOrder on|off
Défaut: | SSLHonorCipherOrder off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Normalement, ce sont les préférences du client qui sont prises en compte lors du choix d'un algorithme de chiffrement au cours d'une négociation SSLv3 ou TLSv1. Si cette directive est activée, ce sont les préférences du serveur qui seront prises en compte à la place.

Exemple

SSLHonorCipherOrder on

Directive SSLInsecureRenegotiation

Description: | Option permettant d'activer le support de la renégociation non sécurisée
Syntaxe: | SSLInsecureRenegotiation on|off
Défaut: | SSLInsecureRenegotiation off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible depuis httpd 2.2.15, si une version 0.9.8m ou supérieure d'OpenSSL est utilisée

Comme il a été spécifié, toutes les versions des protocoles SSL et TLS (jusqu'à la version 1.2 de TLS incluse) étaient vulnérables à une attaque de type Man-in-the-Middle (CVE-2009-3555) au cours d'une renégociation. Cette vulnérabilité permettait à un attaquant de préfixer la requête HTTP (telle qu'elle était vue du serveur) avec un texte choisi. Une extension du protocole a été développée pour corriger cette vulnérabilité, sous réserve qu'elle soit supportée par le client et le serveur.

Si mod_ssl est lié à une version 0.9.8m ou supérieure d'OpenSSL, par défaut, la renégociation n'est accordée qu'aux clients qui supportent la nouvelle extension du protocole. Si cette directive est activée, la renégociation sera accordée aux anciens clients (non patchés), quoique de manière non sécurisée

Avertissement à propos de la sécurité

Si cette directive est activée, les connexions SSL seront vulnérables aux attaques de type préfixe Man-in-the-Middle comme décrit dans CVE-2009-3555.

Exemple

SSLInsecureRenegotiation on

La variable d'environnement SSL_SECURE_RENEG peut être utilisée dans un script SSI ou CGI pour déterminer si la renégociation sécurisée est supportée pour une connexion SSL donnée.

Directive SSLOCSPDefaultResponder

Description: | Définit l'URI du répondeur par défaut pour la validation OCSP
Syntaxe: | SSLOCSDefaultResponder uri
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le répondeur OCSP par défaut. Si la directive SSLOCSPOverrideResponder n'est pas activée, l'URI spécifié ne sera utilisé que si aucun URI de répondeur n'est spécifié dans le certificat en cours de vérification.

Directive SSLOCSPEnable

Description: | Active la validation OCSP de la chaîne de certificats du client
Syntaxe: | SSLOCSPEnable on|off
Défaut: | SSLOCSPEnable off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet d'activer la validation OCSP de la chaîne de certificats du client. Si elle est activée, les certificats de la chaîne de certificats du client seront validés auprès d'un répondeur OCSP, une fois la vérification normale effectuée (vérification des CRLs incluse).

Le répondeur OCSP utilisé est soit extrait du certificat lui-même, soit spécifié dans la configuration ; voir les directives SSLOCSPDefaultResponder et SSLOCSPOverrideResponder.

Exemple

SSLVerifyClient on
SSLOCSPEnable on
SSLOCSPDefaultResponder "http://responder.example.com:8888/responder"
SSLOCSPOverrideResponder on

Directive SSLOCSPNoverify

Description: | Evite la vérification des certificats des répondeurs OCSP
Syntaxe: | SSLOCSPNoverify On/Off
Défaut: | SSLOCSPNoverify Off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible à partir de la version 2.4.26 du serveur HTTP Apache, sous réserve d'utiliser une version 0.9.7 ou supérieure d'OpenSSL

Cette directive permet d'éviter la vérification des certificats des répondeurs OCSP, ce qui peut s'avérer utile lorsqu'on teste un serveur OCSP.

Directive SSLOCSPOverrideResponder

Description: | Force l'utilisation de l'URI du répondeur par défaut pour la validation OCSP
Syntaxe: | SSLOCSPOverrideResponder on|off
Défaut: | SSLOCSPOverrideResponder off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Force l'utilisation, au cours d'une validation OCSP de certificat, du répondeur OCSP par défaut spécifié dans la configuration, que le certificat en cours de vérification fasse mention d'un répondeur OCSP ou non.

Directive SSLOCSPProxyURL

Description: | Adresse de mandataire à utiliser pour les requêtes OCSP
Syntaxe: | SSLOCSPProxyURL url
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible à partir de la version 2.4.19 du serveur HTTP Apache

Cette directive permet de définir l'URL d'un mandataire HTTP qui devra être utilisé pour toutes les requêtes vers un répondeur OCSP.

Directive SSLOCSPResponderCertificateFile

Description: | Fournit un jeu de certificats de confiance du répondeur OCSP avec encodage PEM
Syntaxe: | SSLOCSPResponderCertificateFile file
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible à partir de la version 2.4.26 du serveur HTTP Apache, sous réserve d'utiliser une version 0.9.7 ou supérieure d'OpenSSL

Cette directive permet de définir un fichier contenant une liste de certificats de confiance du répondeur OCSP à utiliser au cours de la validation du certificat du répondeur OCSP. Les certificats fournis peuvent être considérés comme de confiance sans avoir à effectuer de vérifications supplémentaires. Ce processus de validation du certificat du répondeur OCSP intervient en général lorsque ce dernier est autosigné ou tout simplement absent de la réponse OCSP.

Directive SSLOCSPResponderTimeout

Description: | Délai d'attente pour les requêtes OCSP
Syntaxe: | SSLOCSPResponderTimeout secondes
Défaut: | SSLOCSPResponderTimeout 10
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette option permet de définir le délai d'attente pour les requêtes à destination des répondeurs OCSP, lorsque la directive SSLOCSPEnable est à on.

Directive SSLOCSPResponseMaxAge

Description: | Age maximum autorisé pour les réponses OCSP
Syntaxe: | SSLOCSPResponseMaxAge secondes
Défaut: | SSLOCSPResponseMaxAge -1
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette option permet de définir l'âge maximum autorisé (la "fraicheur") des réponses OCSP. La valeur par défault (-1) signifie qu'aucun âge maximum n'est défini ; autrement dit, les réponses OCSP sont considérées comme valides tant que la valeur de leur champ nextUpdate se situe dans le futur.

Directive SSLOCSPResponseTimeSkew

Description: | Dérive temporelle maximale autorisée pour la validation des réponses OCSP
Syntaxe: | SSLOCSPResponseTimeSkew secondes
Défaut: | SSLOCSPResponseTimeSkew 300
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette option permet de définir la dérive temporelle maximale autorisée pour les réponses OCSP (lors de la vérification des champs thisUpdate et nextUpdate).

Directive SSLOCSPUseRequestNonce

Description: | Use a nonce within OCSP queries
Syntaxe: | SSLOCSPUseRequestNonce on|off
Défaut: | SSLOCSPUseRequestNonce on
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Available in httpd 2.4.10 and later

La documentation de cette directive n'a pas encore t traduite. Veuillez vous reporter la version en langue anglaise.

Directive SSLOpenSSLConfCmd

Description: | Configuration des paramètres d'OpenSSL via son API SSL_CONF
Syntaxe: | SSLOpenSSLConfCmd commande valeur
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible depuis la version 2.4.8 du serveur HTTP Apache avec OpenSSL 1.0.2 ou supérieur

Cette directive permet à mod_ssl d'accéder à l'API SSL_CONF d'OpenSSL. Il n'est ainsi plus nécessaire d'implémenter des directives supplémentaires pour mod_ssl lorsque de nouvelles fonctionnalités sont ajoutées à OpenSSL, ce qui rend la configuration de ce dernier beaucoup plus souple.

Le jeu de commandes disponibles pour la directive SSLOpenSSLConfCmd dépend de la version d'OpenSSL utilisée pour mod_ssl (la version minimale 1.0.2 est un prérequis). Pour obtenir la liste des commandes supportées, voir la section Supported configuration file commands de la page de manuel d'OpenSSL SSL_CONF_cmd(3).

Certaines commandes peuvent remplacer des directives existantes (comme SSLCipherSuite ou SSLProtocol) ; notez cependant que la syntaxe et/ou les valeurs possibles peuvent différer.

Examples

SSLOpenSSLConfCmd Options -SessionTicket,ServerPreference
SSLOpenSSLConfCmd ECDHParameters brainpoolP256r1
SSLOpenSSLConfCmd ServerInfoFile
"/usr/local/apache2/conf/server-info.pem"
SSLOpenSSLConfCmd Protocol "-ALL, TLSv1.2"
SSLOpenSSLConfCmd SignatureAlgorithms RSA+SHA384:ECDSA+SHA256

Directive SSLOptions

Description: | Configure différentes options d'exécution du moteur SSL
Syntaxe: | SSLOptions [+|-]option ...
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | Options
Statut: | Extension
Module: | mod_ssl

Cette directive permet de contrôler différentes options d'exécution du moteur SSL dans un contexte de répertoire. Normalement, si plusieurs SSLOptions peuvent s'appliquer à un répertoire, c'est la plus spécifique qui est véritablement prise en compte ; les options ne se combinent pas entre elles. Elles se combinent cependant entre elles si elles sont toutes précédées par un symbole plus (+) ou moins (-). Toute option précédée d'un + est ajoutée aux options actuellement en vigueur, et toute option précédée d'un - est supprimée de ces mêmes options.

Les options disponibles sont :

  • StdEnvVars

    Lorsque cette option est activée, le jeu standard de variables d'environnement SSL relatives à CGI/SSI est créé. Cette option est désactivée par défaut pour des raisons de performances, car l'extraction des informations constitue une opération assez coûteuse en ressources. On n'active donc en général cette option que pour les requêtes CGI et SSI.

  • ExportCertData

    Lorsque cette option est activée, des variables d'environnement CGI/SSI supplémentaires sont créées : SSL_SERVER_CERT, SSL_CLIENT_CERT et SSL_CLIENT_CERT_CHAIN_n (avec n = 0,1,2,..). Elles contiennent les certificats X.509 codés en PEM du serveur et du client pour la connexion HTTPS courante, et peuvent être utilisées par les scripts CGI pour une vérification de certificat plus élaborée. De plus, tous les autres certificats de la chaîne de certificats du client sont aussi fournis. Tout ceci gonfle un peu l'environnement, et c'est la raison pour laquelle vous ne devez activer cette option qu'à la demande.

  • FakeBasicAuth

    Lorsque cette option est activée, le Nom Distinctif (DN) sujet du certificat client X509 est traduit en un nom d'utilisateur pour l'autorisation HTTP de base. Cela signifie que les méthodes d'authentification standard d'Apache peuvent être utilisées pour le contrôle d'accès. Le nom d'utilisateur est tout simplement le Sujet du certificat X509 du client (il peut être déterminé en utilisant la commande OpenSSL openssl x509 : openssl x509 -noout -subject -in certificat.crt). Notez qu'aucun mot de passe n'est envoyé par l'utilisateur. Chaque entrée du fichier des utilisateurs doit comporter ce mot de passe : ``xxj31ZMTZzkVA'', qui est la version chiffrée en DES du mot ``password''. Ceux qui travaillent avec un chiffrement basé sur MD5 (par exemple sous FreeBSD ou BSD/OS, etc...) doivent utiliser le condensé MD5 suivant pour le même mot : ``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''.

    Notez que la directive AuthBasicFake implémentée par le module mod_auth_basic peut être utilisée d'une manière plus générale comme simulation d'authentification basique, ce qui permet de contrôler la structure nom utilisateur/mot de passe.

  • StrictRequire

    Cette option force l'interdiction d'accès lorsque SSLRequireSSL ou SSLRequire a décidé que l'accès devait être interdit. Par défaut, dans le cas où une directive ``Satisfy any'' est utilisée, et si d'autres restrictions d'accès ont été franchies, on passe en général outre l'interdiction d'accès due à SSLRequireSSL ou SSLRequire (parce que c'est ainsi que le mécanisme Satisfy d'Apache doit fonctionner). Pour des restrictions d'accès plus strictes, vous pouvez cependant utiliser SSLRequireSSL et/ou SSLRequire en combinaison avec une option ``SSLOptions +StrictRequire''. Une directive ``Satisfy Any'' n'a alors aucune chance d'autoriser l'accès si mod_ssl a décidé de l'interdire.

  • OptRenegotiate

    Cette option active la gestion optimisée de la renégociation des connexions SSL intervenant lorsque les directives SSL sont utilisées dans un contexte de répertoire. Par défaut un schéma strict est appliqué, et chaque reconfiguration des paramètres SSL au niveau du répertoire implique une phase de renégociation SSL complète. Avec cette option, mod_ssl essaie d'éviter les échanges non nécessaires en effectuant des vérifications de paramètres plus granulaires (mais tout de même efficaces). Néanmoins, ces vérifications granulaires peuvent ne pas correspondre à ce qu'attend l'utilisateur, et il est donc recommandé de n'activer cette option que dans un contexte de répertoire.

  • LegacyDNStringFormat

    Cette option permet d'agir sur la manière dont les valeurs des variables SSL_{CLIENT,SERVER}_{I,S}_DN sont formatées. Depuis la version 2.3.11, Apache HTTPD utilise par défaut un format compatible avec la RFC 2253. Ce format utilise des virgules comme délimiteurs entre les attributs, permet l'utilisation de caractères non-ASCII (qui sont alors convertis en UTF8), échappe certains caractères spéciaux avec des slashes inversés, et trie les attributs en plaçant l'attribut "C" en dernière position.

    Si l'option LegacyDNStringFormat est présente, c'est l'ancien format qui sera utilisé : les attributs sont triés avec l'attribut "C" en première position, les séparateurs sont des slashes non inversés, les caractères non-ASCII ne sont pas supportés et le support des caractères spéciaux n'est pas fiable.

Exemple

SSLOptions +FakeBasicAuth -StrictRequire
<Files ~ "\.(cgi|shtml)$">
    SSLOptions +StdEnvVars -ExportCertData
</Files>

Directive SSLPassPhraseDialog

Description: | Méthode utilisée pour entrer le mot de passe pour les clés privées chiffrées
Syntaxe: | SSLPassPhraseDialog type
Défaut: | SSLPassPhraseDialog builtin
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ssl

Lors de son démarrage, Apache doit lire les différents fichiers de certificats (voir la directive SSLCertificateFile) et de clés privées (voir la directive SSLCertificateKeyFile) des serveurs virtuels où SSL est activé. Comme, pour des raisons de sécurité, les fichiers de clés privées sont en général chiffrés, mod_ssl doit demander à l'administrateur un mot de passe pour déchiffrer ces fichiers. L'argument type permet de choisir la manière dont cette demande peut être formulée parmi les trois suivantes :

  • builtin

    C'est la méthode par défaut, et un dialogue interactive de terminal s'ouvre au cours du démarrage juste avant qu'Apache ne se détache du terminal. A ce moment, l'administrateur doit entrer manuellement un mot de passe pour chaque fichier de clé privée chiffré. Etant donné qu'il peut y avoir un grand nombre de serveurs virtuels configurés avec SSL activé, le protocole de réutilisation suivant est utilisé pour minimiser le dialogue : lorsqu'un fichier de clé privée est chiffré, tous les mots de passe connus (au début, il n'y en a aucun, bien entendu) sont essayés. Si l'un de ces mots de passe connus convient, aucun dialogue ne s'ouvrira pour ce fichier de clé privée particulier. Si aucun ne convient, un autre mot de passe sera demandé à partir du terminal et sera mis en mémoire pour le fichier de clé privée suivant (pour lequel il pourra éventuellement être réutilisé).

    Cette méthode confère à mod_ssl une grande souplesse (car pour N fichiers de clé privée chiffrés, vous pouvez utiliser N mots de passe différents - mais vous devrez alors tous les fournir, bien entendu), tout en minimisant le dialogue de terminal (vous pouvez en effet utiliser un seul mot de passe pour les N fichiers de clé privée et vous n'aurez alors à l'entrer qu'une seule fois).

  • |/chemin/vers/programme [arguments...]

    Ce mode permet d'utiliser un programme externe qui va se présenter comme une redirection vers un périphérique d'entrée particulier ; le texte de prompt standard utilisé pour le mode builtin est envoyé au programme sur stdin, et celui-ci doit renvoyer des mots de passe sur stdout. Si plusieurs mots de passe sont requis (ou si un mot de passe incorrect a été entré), un texte de prompt supplémentaire sera écrit après le retour du premier mot de passe, et d'autres mots de passe devront alors être réécrits.

  • exec:/chemin/vers/programme

    Ici, un programme externe est appelé au démarrage du serveur pour chaque fichier de clé privée chiffré.Il est appelé avec deux arguments (le premier est de la forme ``nom-serveur:port'', le second est ``RSA'', ``DSA'', ``ECC'' ou un index entier commençant à 3 si plus de 3 clés ont été configurées), qui indiquent pour quels serveur et algorithme il doit écrire le mot de passe correspondant sur stdout. Avec les versions 2.4.8 (non réalisée) et 2.4.9, il est appelé avec un seul argument, une chaîne de la forme "servername:portnumber:index" (où index est un nombre entier commençant à zéro), qui spécifie le serveur, le port TCP et un numéro de certificat. Le but recherché est l'exécution de vérifications de sécurité préalables permettant de s'assurer que le système n'est pas victime d'une attaque, et de ne fournir le mot de passe que si toutes les vérifications ont été effectuées avec succès.

    Ces vérifications de sécurité, ainsi que la manière dont le mot de passe est déterminé peuvent être aussi sophistiqués que vous le désirez. Mod_ssl ne définit que l'interface : un programme exécutable qui écrit le mot de passe sur stdout. Ni plus, ni moins ! Ainsi, si vous êtes vraiment paranoïaque en matière de sécurité, voici votre interface. Tout le reste doit être confié à l'administrateur à titre d'exercice, car les besoins en sécurité locale sont très différents.

    L'algorithme de réutilisation est utilisé ici aussi. En d'autres termes, le programme externe n'est appelé qu'une fois par mot de passe unique.

Exemple

SSLPassPhraseDialog "exec:/usr/local/apache/sbin/pp-filter"

Directive SSLProtocol

Description: | Indique les versions du protocole SSL/TLS disponibles
Syntaxe: | SSLProtocol [+|-]protocole ...
Défaut: | SSLProtocol all -SSLv3 (jusqu'à la version 2.4.16 : all)
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir quelles versions du protocole SSL/TLS seront acceptées lors de l'initialisation d'une nouvelle connexion.

Les protocoles disponibles sont les suivants (sensibles à la casse) :

  • SSLv3

    Il s'agit du protocole Secure Sockets Layer (SSL) version 3.0 de Netscape Corporation. C'est le successeur de SSLv2 et le prédécesseur de TLSv1, mais est considéré comme obsolète dans la RFC 7568

  • TLSv1

    Il s'agit du protocole Transport Layer Security (TLS) version 1.0. C'est le successeur de SSLv3, et il est défini dans la RFC2246. Il est supporté par la plupart des clients.

  • TLSv1.1 (à partir de la version 1.0.1 d'OpenSSL)

    Une révision du protocole TLS 1.0 définie dans la RFC 4346.

  • TLSv1.2 (à partir de la version 1.0.1 d'OpenSSL)

    Une révision du protocole TLS 1.1 définie dans la RFC 5246.

  • all

    C'est un raccourci pour ``+SSLv3 +TLSv1'' ou - à partir de la version 1.0.1 d'OpenSSL - ``+SSLv3 +TLSv1 +TLSv1.1 +TLSv1.2'' (sauf si OpenSSL a été compilé avec l'option ``no-ssl3'', auquel cas all n'inclura pas +SSLv3).

Exemple

SSLProtocol TLSv1

Directive SSLProxyCACertificateFile

Description: | Fichier contenant la concaténation des certificats de CA codés en PEM pour l'authentification des serveurs distants
Syntaxe: | SSLProxyCACertificateFile file-path
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier tout-en-un où sont stockés les certificats des Autorités de Certification (CA) pour les serveurs distants auxquels vous avez à faire. On les utilise lors de l'authentification du serveur distant. Un tel fichier contient la simple concaténation des différents fichiers de certificats codés en PEM, classés par ordre de préférence. On peut utiliser cette directive à la place et/ou en complément de la directive SSLProxyCACertificatePath.

Exemple

SSLProxyCACertificateFile
"/usr/local/apache2/conf/ssl.crt/ca-bundle-serveur.distant.crt"

Directive SSLProxyCACertificatePath

Description: | Répertoire des certificats de CA codés en PEM pour l'authentification des serveurs distants
Syntaxe: | SSLProxyCACertificatePath chemin-répertoire
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de spécifier le répertoire où sont stockés les certificats des Autorités de Certification (CAs) pour les serveurs distants auxquels vous avez à faire. On les utilise pour vérifier le certificat du serveur distant lors de l'authentification de ce dernier.

Les fichiers de ce répertoire doivent être codés en PEM et ils sont accédés via des noms de fichier sous forme de condensés ou hash. Il ne suffit donc pas de placer les fichiers de certificats dans ce répertoire : vous devez aussi créer des liens symboliques nommés valeur-de-hashage.N, et vous devez toujours vous assurer que ce répertoire contient les liens symboliques appropriés.

Exemple

SSLProxyCACertificatePath "/usr/local/apache2/conf/ssl.crt/"

Directive SSLProxyCARevocationCheck

Description: | Active la vérification des révocations basée sur les CRLs pour l'authentification du serveur distant
Syntaxe: | SSLProxyCARevocationCheck chain|leaf|none
Défaut: | SSLProxyCARevocationCheck none
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Active la vérification des révocations basée sur les Listes de révocations de Certificats (CRL) pour les serveurs distants auxquels vous vous connectez. A moins une des directives SSLProxyCARevocationFile ou SSLProxyCARevocationPath doit être définie. Lorsque cette directive est définie à chain (valeur recommandée), les vérifications CRL sont effectuées sur tous les certificats de la chaîne, alors que la valeur leaf limite la vérification au certificat hors chaîne (la feuille).

Lorsque la directive est définie à chain ou leaf, les CRLs doivent être disponibles pour que la validation réussisse

Avant la version 2.3.15, les vérifications CRL dans mod_ssl réussissaient même si aucune CRL n'était trouvée dans les chemins définis par les directives SSLProxyCARevocationFile ou SSLProxyCARevocationPath. Le comportement a changé avec l'introduction de cette directive : lorsque la vérification est activée, les CRLs doivent être présentes pour que la validation réussisse ; dans le cas contraire, elle échouera avec une erreur "CRL introuvable".

Exemple

SSLProxyCARevocationCheck chain

Directive SSLProxyCARevocationFile

Description: | Fichier contenant la concaténation des CRLs de CA codés en PEM pour l'authentification des serveurs distants
Syntaxe: | SSLProxyCARevocationFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier tout-en-un où sont rassemblées les Listes de Révocation de Certificats (CRLs) des Autorités de certification (CAs) pour les serveurs distants auxquels vous avez à faire. On les utilise pour l'authentification des serveurs distants. Un tel fichier contient la simple concaténation des différents fichiers de CRLs codés en PEM, classés par ordre de préférence. Cette directive peut être utilisée à la place et/ou en complément de la directive SSLProxyCARevocationPath.

Exemple

SSLProxyCARevocationFile
"/usr/local/apache2/conf/ssl.crl/ca-bundle-serveur.distant.crl"

Directive SSLProxyCARevocationPath

Description: | Répertoire des CRLs de CA codés en PEM pour l'authentification des serveurs distants
Syntaxe: | SSLProxyCARevocationPath chemin-répertoire
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le répertoire où sont stockées les Listes de Révocation de Certificats (CRL) des Autorités de Certification (CAs) pour les serveurs distants auxquels vous avez à faire. On les utilise pour révoquer les certificats des serveurs distants au cours de l'authentification de ces derniers.

Les fichiers de ce répertoire doivent être codés en PEM et ils sont accédés via des noms de fichier sous forme de condensés ou hash. Il ne suffit donc pas de placer les fichiers de CRL dans ce répertoire : vous devez aussi créer des liens symboliques nommés valeur-de-hashage.rN, et vous devez toujours vous assurer que ce répertoire contient les liens symboliques appropriés.

Exemple

SSLProxyCARevocationPath "/usr/local/apache2/conf/ssl.crl/"

Directive SSLProxyCheckPeerCN

Description: | Configuration de la vérification du champ CN du certificat du serveur distant
Syntaxe: | SSLProxyCheckPeerCN on|off
Défaut: | SSLProxyCheckPeerCN on
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir si le champ CN du certificat du serveur distant doit être comparé au nom de serveur de l'URL de la requête. S'ils ne correspondent pas, un code d'état 502 (Bad Gateway) est envoyé. A partir de la version 2.4.5, SSLProxyCheckPeerCN a été remplacé par SSLProxyCheckPeerName.

De la version 2.4.5 à la version 2.4.20, spécifier SSLProxyCheckPeerName off était suffisant pour obtenir ce comportement (car la valeur par défaut de SSLProxyCheckPeerCN était on). Avec ces versions, les deux directives doivent être définies à off pour éviter toute validation du nom de certificat du serveur distant, et de nombreux utilisateurs ont signalé ce comportement comme très perturbant.

A partir de la version 2.4.21, toutes les configurations qui activent au moins une des deux directives SSLProxyCheckPeerName ou SSLProxyCheckPeerCN adopteront le nouveau comportement de la directive SSLProxyCheckPeerName, et toutes les configurations qui désactivent une des deux directives SSLProxyCheckPeerName ou SSLProxyCheckPeerCN éviteront toute validation du nom de certificat du serveur distant. Seule la configuration suivante permettra de retrouver la comparaison de CN traditionnelle pour les versions 2.4.21 et supérieures :

Exemple

SSLProxyCheckPeerCN on
SSLProxyCheckPeerName off

Directive SSLProxyCheckPeerExpire

Description: | Configuration de la vérification de l'expiration du certificat du serveur distant
Syntaxe: | SSLProxyCheckPeerExpire on|off
Défaut: | SSLProxyCheckPeerExpire on
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir si l'expiration du certificat du serveur distant doit être vérifiée ou non. Si la vérification échoue, un code d'état 502 (Bad Gateway) est envoyé.

Exemple

SSLProxyCheckPeerExpire on

Directive SSLProxyCheckPeerName

Description: | Configure la vérification du nom d'hôte dans les certificats serveur distants
Syntaxe: | SSLProxyCheckPeerName on|off
Défaut: | SSLProxyCheckPeerName on
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible à partir de la version 2.4.5 du serveur HTTP Apache

Cette directive permet de configurer la vérification du nom d'hôte pour les certificats serveur lorsque mod_ssl agit en tant que client SSL. La vérification réussit si le nom d'hôte de l'URI de la requête correspond à un des attributs CN du sujet du certificat, ou à l'extension subjectAltName. Si la vérification échoue, la requête SSL avorte, et un code d'erreur 502 (Bad Gateway) est renvoyé.

Les caractères génériques sont supportés dans certains cas bien spécifiques : une entrée subjectAltName de type dNSName ou les attributs CN commençant par *. correspondront à tout nom d'hôte comportant le même nombre de champs et le même suffixe ; par exemple, *.example.org correspondra à foo.example.org, mais pas à foo.bar.example.org car le nombre d'éléments dans les nom est différent.

Cette fonctionnalité a été introduite avec la version 2.4.5 et l'emporte sur la directive SSLProxyCheckPeerCN qui ne comparait que la valeur exacte du premier attribut CN avec le nom d'hôte. Cependant, de nombreux utilisateurs étaient déconcertés par le comportement induit par l'utilisation de ces deux directives individuellement, si bien que ce comportement a été amélioré avec la version 2.4.21. Voir la description de la directive SSLProxyCheckPeerCN pour le comportement original et des détails à propos de ces améliorations.

Directive SSLProxyCipherSuite

Description: | Algorithmes de chiffrement disponibles pour la négociation lors de l'initialisation d'une connexion SSL de mandataire
Syntaxe: | SSLProxyCipherSuite algorithmes
Défaut: | SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive est équivalente à la directive SSLCipherSuite, mais s'applique à une connexion de mandataire. Veuillez vous reporter à la directive SSLCipherSuite pour plus d'informations.

Directive SSLProxyEngine

Description: | Interrupteur marche/arrêt du moteur de mandataire SSL
Syntaxe: | SSLProxyEngine on|off
Défaut: | SSLProxyEngine off
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet d'activer/désactiver l'utilisation du moteur de protocole SSL/TLS pour le mandataire. On l'utilise en général à l'intérieur d'une section <VirtualHost> pour activer le protocole SSL/TLS dans le cadre d'un mandataire pour un serveur virtuel particulier. Par défaut, le moteur de protocole SSL/TLS est désactivé pour la fonction de mandataire du serveur principal et de tous les serveurs virtuels configurés.

Notez que la directive SSLProxyEngine ne doit généralement pas être utilisée dans le cadre d'un serveur virtuel qui agit en tant que mandataire direct (via les directives <Proxy> ou ProxyRequests). SSLProxyEngine n'est pas nécessaire pour activer un serveur mandataire direct pour les requêtes SSL/TLS.

Exemple

<VirtualHost _default_:443>
    SSLProxyEngine on
    #...
</VirtualHost>

Directive SSLProxyMachineCertificateChainFile

Description: | Fichier de certificats de CA encodés PEM concaténés permettant au mandataire de choisir un certificat
Syntaxe: | SSLProxyMachineCertificateChainFile nom-fichier
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier global où est enregistrée la chaîne de certification pour tous les certificats clients utilisés. Elle est nécessaire si le serveur distant présente une liste de certificats de CA qui ne sont pas les signataires directs d'un des certificats clients configurés.

Ce fichier contient tout simplement la concaténation des différents fichiers de certificats encodés PEM. Au démarrage, chaque certificat client configuré est examiné et une chaîne de certification est construite.

Avertissement en matière de sécurité

Si cette directive est définie, tous les certificats contenus dans le fichier spécifié seront considérés comme étant de confiance, comme s'ils étaient aussi désignés dans la directive SSLProxyCACertificateFile.

Exemple

SSLProxyMachineCertificateChainFile
"/usr/local/apache2/conf/ssl.crt/proxyCA.pem"

Directive SSLProxyMachineCertificateFile

Description: | Fichier contenant la concaténation des clés et certificats clients codés en PEM que le mandataire doit utiliser
Syntaxe: | SSLProxyMachineCertificateFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le fichier tout-en-un où sont stockés les clés et certificats permettant au serveur mandataire de s'authentifier auprès des serveurs distants.

Le fichier spécifié est la simple concaténation des différents fichiers de certificats codés en PEM, classés par ordre de préférence. Cette directive s'utilise à la place ou en complément de la directive SSLProxyMachineCertificatePath.

Actuellement, les clés privées chiffrées ne sont pas supportées.

Exemple

SSLProxyMachineCertificateFile
"/usr/local/apache2/conf/ssl.crt/proxy.pem"

Directive SSLProxyMachineCertificatePath

Description: | Répertoire des clés et certificats clients codés en PEM que le mandataire doit utiliser
Syntaxe: | SSLProxyMachineCertificatePath chemin-répertoire
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le répertoire où sont stockés les clés et certificats permettant au serveur mandataire de s'authentifier auprès des serveurs distants.

Les fichiers de ce répertoire doivent être codés en PEM et ils sont accédés via des noms de fichier sous forme de condensés ou hash. Vous devez donc aussi créer des liens symboliques nommés valeur-de-hashage.N, et vous devez toujours vous assurer que ce répertoire contient les liens symboliques appropriés.

Actuellement, les clés privées chiffrées ne sont pas supportées.

Exemple

SSLProxyMachineCertificatePath "/usr/local/apache2/conf/proxy.crt/"

Directive SSLProxyProtocol

Description: | Définit les protocoles SSL disponibles pour la fonction de mandataire
Syntaxe: | SSLProxyProtocol [+|-]protocole ...
Défaut: | SSLProxyProtocol all -SSLv3 (jusqu'à la version 2.4.16: all)
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir les protocoles SSL que mod_ssl peut utiliser lors de l'élaboration de son environnement de serveur pour la fonction de mandataire. Il ne se connectera qu'aux serveurs utilisant un des protocoles spécifiés.

Veuillez vous reporter à la directive SSLProtocol pour plus d'informations.

Directive SSLProxyVerify

Description: | Niveau de vérification du certificat du serveur distant
Syntaxe: | SSLProxyVerify niveau
Défaut: | SSLProxyVerify none
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Lorsqu'un mandataire est configuré pour faire suivre les requêtes vers un serveur SSL distant, cette directive permet de configurer la vérification du certificat de ce serveur distant.

Les valeurs de niveaux disponibles sont les suivantes :

  • none: aucun certificat n'est requis pour le serveur distant
  • optional: le serveur distant peut présenter un certificat valide
  • require: le serveur distant doit présenter un certificat valide
  • optional_no_ca: le serveur distant peut présenter un certificat valide
    mais il n'est pas nécessaire qu'il soit vérifiable (avec succès).

En pratique, seuls les niveaux none et require sont vraiment intéressants, car le niveau optional ne fonctionne pas avec tous les serveurs, et le niveau optional_no_ca va tout à fait à l'encontre de l'idée que l'on peut se faire de l'authentification (mais peut tout de même être utilisé pour établir des pages de test SSL, etc...).

Exemple

SSLProxyVerify require

Directive SSLProxyVerifyDepth

Description: | Niveau de profondeur maximum dans les certificats de CA lors de la vérification du certificat du serveur distant
Syntaxe: | SSLProxyVerifyDepth niveau
Défaut: | SSLProxyVerifyDepth 1
Contexte: | configuration du serveur, serveur virtuel,
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le niveau de profondeur maximum jusqu'auquel mod_ssl doit aller au cours de sa vérification avant de décider que le serveur distant ne possède pas de certificat valide.

La profondeur correspond en fait au nombre maximum de fournisseurs de certificats intermédiaires, c'est à dire le nombre maximum de certificats de CA que l'on peut consulter lors de la vérification du certificat du serveur distant. Une profondeur de 0 signifie que seuls les certificats de serveurs distants auto-signés sont acceptés, et la profondeur par défaut de 1 que le certificat du serveur distant peut être soit auto-signé, soit signé par une CA connue directement du serveur (en d'autres termes, le certificat de CA est référencé par la directive SSLProxyCACertificatePath), etc...

Exemple

SSLProxyVerifyDepth 10

Directive SSLRandomSeed

Description: | Source de déclenchement du Générateur de Nombres Pseudo-Aléatoires (PRNG)
Syntaxe: | SSLRandomSeed contexte source [nombre]
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir une ou plusieurs sources de déclenchement du Générateur de Nombres Pseudo-Aléatoires (PRNG) dans OpenSSL au démarrage du serveur (si contexte a pour valeur startup) et/ou juste avant l'établissement d'une nouvelle connexion SSL (si contexte a pour valeur connect). Cette directive ne peut être utilisée qu'au niveau du serveur global car le PRNG est un service global.

Les différentes valeurs de source disponibles sont :

  • builtin

    Cette source de déclenchement intégrée est toujours disponible. Son utilisation consomme un minimum de cycles CPU en cours d'exécution, et son utilisation ne présente de ce fait aucun problème. La source utilisée pour déclencher le PRNG contient la date courante, l'identifiant du processus courant et (si disponible) un extrait de 1Ko aléatoirement choisi de la structure d'Apache pour les échanges inter-processus. Ceci présente un inconvénient car le caractère aléatoire de cette source n'est pas vraiment fort, et au démarrage (lorsque la structure d'échanges n'est pas encore disponible), cette source ne produit que quelques octets d'entropie. Vous devez donc toujours utiliser une source de déclenchement additionnelle, au moins pour le démarrage.

  • file:/chemin/vers/source

    Cette variante utilise un fichier externe file:/chemin/vers/source comme source de déclenchement du PRNG. Lorsque nombre est spécifié, seuls les nombre premiers octets du fichier forment l'entropie (et nombre est fourni comme premier argument à /chemin/vers/source). Lorsque nombre n'est pas spécifié, l'ensemble du fichier forme l'entropie (et 0 est fourni comme premier argument à /chemin/vers/source). Utilisez cette source en particulier au démarrage, par exemple avec un fichier de périphérique /dev/random et/ou /dev/urandom (qui sont en général présent sur les plate-formes dérivées d'Unix modernes comme FreeBSD et Linux).

    Soyez cependant prudent : en général, /dev/random ne fournit que l'entropie dont il dispose réellement ; en d'autres termes, lorsque vous demandez 512 octets d'entropie, si le périphérique ne dispose que de 100 octets, deux choses peuvent se produire : sur certaines plates-formes, vous ne recevez que les 100 octets, alors que sur d'autres, la lecture se bloque jusqu'à ce qu'un nombre suffisant d'octets soit disponible (ce qui peut prendre beaucoup de temps). Il est préférable ici d'utiliser le périphérique /dev/urandom, car il ne se bloque jamais et fournit vraiment la quantité de données demandées. Comme inconvénient, les données reçues ne sont pas forcément de la meilleure qualité.

  • exec:/chemin/vers/programme

    Cette variante utilise un exécutable externe /chemin/vers/programme comme source de déclenchement du PRNG. Lorsque nombre est spécifié, seules les nombre premiers octets de son flux stdout forment l'entropie. Lorsque nombre n'est pas spécifié, l'intégralité des données produites sur stdout forment l'entropie. N'utilisez cette variante qu'au démarrage où une source de déclenchement fortement aléatoire est nécessaire, en utilisant un programme externe (comme dans l'exemple ci-dessous avec l'utilitaire truerand basé sur la bibliothèque truerand de AT&T que vous trouverez dans la distribution de mod_ssl). Bien entendu, l'utilisation de cette variante dans un contexte "connection" ralentit le serveur de manière trop importante, et en général, vous devez donc éviter d'utiliser des programmes externes dans ce contexte.

  • egd:/chemin/vers/socket-egd (Unix seulement)

    Cette variante utilise le socket de domaine Unix du Démon Générateur d'Entropie externe ou Entropy Gathering Daemon ou EGD (voir http://www.lothar.com/tech /crypto/) pour déclencher le PRNG. N'utilisez cette variante que si votre plate-forme ne possède pas de périphérique random ou urandom.

Exemple

SSLRandomSeed startup builtin
SSLRandomSeed startup "file:/dev/random"
SSLRandomSeed startup "file:/dev/urandom" 1024
SSLRandomSeed startup "exec:/usr/local/bin/truerand" 16
SSLRandomSeed connect builtin
SSLRandomSeed connect "file:/dev/random"
SSLRandomSeed connect "file:/dev/urandom" 1024

Directive SSLRenegBufferSize

Description: | Définit la taille du tampon de renégociation SSL
Syntaxe: | SSLRenegBufferSize taille
Défaut: | SSLRenegBufferSize 131072
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ssl

Si une renégociation SSL est requise dans un contexte de répertoire, par exemple avec l'utilisation de SSLVerifyClient dans un bloc Directory ou Location, mod_ssl doit mettre en tampon en mémoire tout corps de requête HTTP en attendant qu'une nouvelle initialisation de connexion SSL puisse être effectuée. Cette directive permet de définir la quantité de mémoire à allouer pour ce tampon.

Notez que dans de nombreuses configurations, le client qui envoie un corps de requête n'est pas forcément digne de confiance, et l'on doit par conséquent prendre en considération la possibilité d'une attaque de type déni de service lorsqu'on modifie la valeur de cette directive.

Exemple

SSLRenegBufferSize 262144

Directive SSLRequire

Description: | N'autorise l'accès que lorsqu'une expression booléenne complexe et arbitraire est vraie
Syntaxe: | SSLRequire expression
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ssl

SSLRequire est obsolète

SSLRequire est obsolète et doit en général être remplacée par l'expression Require. La syntaxe ap_expr de l'expression Require est une extension de la syntaxe de SSLRequire, avec les différences suivantes :

Avec SSLRequire, les opérateurs de comparaison <, <=, ... sont strictement équivalents aux opérateurs lt, le, ... , et fonctionnent selon une méthode qui compare tout d'abord la longueur des deux chaînes, puis l'ordre alphabétique. Les expressions ap_expr, quant à elles, possèdent deux jeux d'opérateurs de comparaison : les opérateurs <, <=, ... effectuent une comparaison alphabétique de chaînes, alors que les opérateurs -lt, -le, ... effectuent une comparaison d'entiers. Ces derniers possèdent aussi des alias sans tiret initial : lt, le, ...

Cette directive permet de spécifier une condition générale d'accès qui doit être entièrement satisfaite pour que l'accès soit autorisé. C'est une directive très puissante, car la condition d'accès spécifiée est une expression booléenne complexe et arbitraire contenant un nombre quelconque de vérifications quant aux autorisations d'accès.

L'expression doit respecter la syntaxe suivante (fournie ici sous la forme d'une notation dans le style de la grammaire BNF) :

expr     ::= "true" | "false"
           | "!" expr
           | expr "&&" expr
           | expr "||" expr
           | "(" expr ")"
           | comp

comp     ::= word "==" word | word "eq" word
           | word "!=" word | word "ne" word
           | word "<"  word | word "lt" word
           | word "<=" word | word "le" word
           | word ">"  word | word "gt" word
           | word ">=" word | word "ge" word
           | word "in" "{" wordlist "}"
           | word "in" "PeerExtList(" word ")"
           | word "=~" regex
           | word "!~" regex

wordlist ::= word
           | wordlist "," word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

Pour varname, toute variable décrite dans Variables d'environnement pourra être utilisée. Pour funcname, vous trouverez la liste des fonctions disponibles dans la documentation ap_expr.

expression est interprétée et traduite sous une forme machine interne lors du chargement de la configuration, puis évaluée lors du traitement de la requête. Dans le contexte des fichiers .htaccess, expression est interprétée et exécutée chaque fois que le fichier .htaccess intervient lors du traitement de la requête.

Exemple

SSLRequire (    %{SSL_CIPHER} !~ m/^(EXP|NULL)-/                   \
            and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd."          \
            and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}    \
            and %{TIME_WDAY} -ge 1 and %{TIME_WDAY} -le 5          \
            and %{TIME_HOUR} -ge 8 and %{TIME_HOUR} -le 20       ) \
           or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/

La fonction PeerExtList(identifiant objet) recherche une instance d'extension de certificat X.509 identifiée par identifiant objet (OID) dans le certificat client. L'expression est évaluée à true si la partie gauche de la chaîne correspond exactement à la valeur d'une extension identifiée par cet OID (Si plusieurs extensions possèdent le même OID, l'une d'entre elles au moins doit correspondre).

Exemple

SSLRequire "foobar" in PeerExtList("1.2.3.4.5.6")

Notes à propos de la fonction PeerExtList

  • L'identifiant objet peut être spécifié soit comme un nom descriptif reconnu par la bibliothèque SSL, tel que "nsComment", soit comme un OID numérique tel que "1.2.3.4.5.6".

  • Les expressions contenant des types connus de la bibliothèque SSL sont transformées en chaînes avant comparaison. Pour les extensions contenant un type non connu de la bibliothèque SSL, mod_ssl va essayer d'interpréter la valeur s'il s'agit d'un des types ASN.1 primaires UTF8String, IA5String, VisibleString, ou BMPString. Si l'extension correspond à un de ces types, la chaîne sera convertie en UTF-8 si nécessaire, puis comparée avec la partie gauche de l'expression.

Voir aussi

  • Les variables d'environnement dans le serveur HTTP Apache, pour d'autres exemples.
  • Require expr
  • Syntaxe générale des expressions dans le serveur HTTP Apache

Directive SSLRequireSSL

Description: | Interdit l'accès lorsque la requête HTTP n'utilise pas SSL
Syntaxe: | SSLRequireSSL
Contexte: | répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ssl

Cette directive interdit l'accès si HTTP sur SSL (c'est à dire HTTPS) n'est pas activé pour la connexion courante. Ceci est très pratique dans un serveur virtuel où SSL est activé ou dans un répertoire pour se protéger des erreurs de configuration qui pourraient donner accès à des ressources protégées. Lorsque cette directive est présente, toutes les requêtes qui n'utilisent pas SSL sont rejetées.

Exemple

SSLRequireSSL

Directive SSLSessionCache

Description: | Type du cache de session SSL global et inter-processus
Syntaxe: | SSLSessionCache type
Défaut: | SSLSessionCache none
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ssl

Cette directive permet de configurer le type de stockage du cache de session SSL global et inter-processus. Ce cache est une fonctionnalité optionnelle qui accélère le traitement parallèle des requêtes. Pour ce qui est des requêtes vers un même processus du serveur (via HTTP keep-alive), OpenSSL met en cache les informations de session SSL en interne. Mais comme les clients modernes demandent des images en ligne et d'autres données via des requêtes parallèles (un nombre de quatre requêtes parallèles est courant), ces requêtes vont être servies par plusieurs processus du serveur pré-déclenchés. Ici, un cache inter-processus permet d'éviter des négociations de session inutiles.

Les quatre types de stockage suivants sont actuellement supportés :

  • none

    Cette valeur désactive le cache de session global et inter-processus, ce qui va ralentir le serveur de manière sensible et peut poser problème avec certains navigateurs, en particulier si les certificats clients sont activés. Cette configuration n'est pas recommandée.

  • nonenotnull

    Cette valeur désactive tout cache de session global et inter-processus. Cependant, elle force OpenSSL à envoyer un identifiant de session non nul afin de s'adapter aux clients bogués qui en nécessitent un.

  • dbm:/chemin/vers/fichier-données

    Cette valeur utilise un fichier de hashage DBM sur disque local pour synchroniser les caches OpenSSL locaux en mémoire des processus du serveur. Ce cache de session peut être sujet à des problèmes de fiabilité sous forte charge. Pour l'utiliser, le module mod_socache_dbm doit être chargé.

  • shmcb:/chemin/vers/fichier-données[(nombre)]

    Cette valeur utilise un tampon cyclique à hautes performances (d'une taille d'environ nombre octets) dans un segment de mémoire partagée en RAM (établi via /chemin/vers/fichier-données, pour synchroniser les caches OpenSSL locaux en mémoire des processus du serveur. C'est le type de cache de session recommandé. Pour l'utiliser, le module mod_socache_shmcb doit être chargé.

  • dc:UNIX:/chemin/vers/socket

    Cette valeur utilise les bibliothèques de mise en cache de sessions distribuée sur distcache. L'argument doit spécifier le serveur ou mandataire à utiliser en utilisant la syntaxe d'adressage distcache ; par exemple, UNIX:/chemin/vers/socket spécifie une socket de domaine Unix (en général un mandataire de dc_client local) ; IP:serveur.example.com:9001 spécifie une adresse IP. Pour l'utiliser, le module mod_socache_dc doit être chargé.

Exemples

SSLSessionCache "dbm:/usr/local/apache/logs/ssl_gcache_data"
SSLSessionCache "shmcb:/usr/local/apache/logs/ssl_gcache_data(512000)"

Le mutex ssl-cache permet de sérialiser l'accès au cache de session afin d'éviter toute corruption. Ce mutex peut être configuré via la directive Mutex.

Directive SSLSessionCacheTimeout

Description: | Nombre de secondes avant l'expiration d'une session SSL dans le cache de sessions
Syntaxe: | SSLSessionCacheTimeout secondes
Défaut: | SSLSessionCacheTimeout 300
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | S'applique aussi à la reprise de session TLS (RFC 5077) à partir de la version 2.4.10 du serveur HTTP Apache

Cette directive permet de définir la durée de vie en secondes des informations stockées dans le cache de sessions SSL global et inter-processus, dans le cache OpenSSL interne en mémoire et pour les sessions réinitialisées par la reprise de session TLS (RFC 5077). elle peut être définie à une valeur d'environ 15 à des fins de test, mais à une valeur très supérieure comme 300 en production.

Exemple

SSLSessionCacheTimeout 600

Directive SSLSessionTicketKeyFile

Description: | Clé de chiffrement/déchiffrement permanente pour les tickets de session TLS
Syntaxe: | SSLSessionTicketKeyFile chemin-fichier
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible depuis la version 2.4.0 du serveur HTTP Apache, sous réserve que l'on utilise une version 0.9.8h ou supérieure d'OpenSSL

Cette directive permet de définir une clé secrète pour le chiffrement et le déchiffrement des tickets de session TLS selon les préconisations de la RFC 5077. Elle a été conçue à l'origine pour les environnements de clusters où les données des sessions TLS doivent être partagées entre plusieurs noeuds. Pour les configurations ne comportant qu'une seule instance de httpd, il est préférable d'utiliser les clés (aléatoires) générées par mod_ssl au démarrage du serveur.

Le fichier doit contenir 48 octets de données aléatoires créées de préférence par une source à haute entropie. Sur un système de type UNIX, il est possible de créer le fichier contenant la clé de la manière suivante :

dd if=/dev/random of=/chemin/vers/fichier.tkey bs=1 count=48

Ces clés doivent être renouvelées fréquemment, car il s'agit du seul moyen d'invalider un ticket de session existant - OpenSSL ne permet pas actuellement de spécifier une limite à la durée de vie des tickets. Une nouvelle clé ne peut être utilisée qu'après avoir redémarré le serveur. Tous les tickets de session existants deviennent invalides après le redémarrage du serveur.

Ce fichier contient des données sensibles et doit donc être protégé par des permissions similaires à celles du fichier spécifié par la directive SSLCertificateKeyFile.

Directive SSLSessionTickets

Description: | Active ou désactive les tickets de session TLS
Syntaxe: | SSLSessionTickets on|off
Défaut: | SSLSessionTickets on
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible à partir de la version 2.4.11 du serveur HTTP Apache, sous réserve d'utiliser OpenSSL version 0.9.8f ou supérieure.

Cette directive permet d'activer ou de désactiver l'utilisation des tickets de session TLS (RFC 5077).

Les tickets de session TLS sont activés par défaut. Les utiliser sans redémarrer le serveur selon une périodicité appropriée (par exemple quotidiennement) compromet cependant le niveau de confidentialité.

Directive SSLSRPUnknownUserSeed

Description: | Source d'aléa pour utilisateur SRP inconnu
Syntaxe: | SSLSRPUnknownUserSeed secret-string
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible depuis la version 2.4.4 du serveur HTTP Apache, si la version 1.0.1 ou supérieure d'OpenSSL est utilisée.

Cette directive permet de définir la source d'aléa à utiliser pour les utilisateurs SRP inconnus, ceci afin de combler les manques en cas d'existence d'un tel utilisateur. Elle définit une chaîne secrète. Si cette directive n'est pas définie, Apache renverra une alerte UNKNOWN_PSK_IDENTITY aux clients qui fournissent un nom d'utilisateur inconnu.

Exemple

SSLSRPUnknownUserSeed "secret"

Directive SSLSRPVerifierFile

Description: | Chemin du fichier de vérification SRP
Syntaxe: | SSLSRPVerifierFile file-path
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible depuis la version 2.4.4 du serveur HTTP Apache, si la version 1.0.1 ou supérieure d'OpenSSL est utilisée.

Cette directive permet d'activer TLS-SRP et de définir le chemin du fichier de vérification OpenSSL SRP (Mot de passe distant sécurisé) contenant les noms d'utilisateurs TLS-SRP, les vérificateurs, les "grains de sel" (salts), ainsi que les paramètres de groupe.

Exemple

SSLSRPVerifierFile "/path/to/file.srpv"

Le fichier de vérification peut être créé via l'utilitaire en ligne de commande openssl :

Création du fichier de vérification SRP

openssl srp -srpvfile passwd.srpv -userinfo "some info" -add username

La valeur affectée au paramètre optionnel -userinfo est enregistrée dans la variable d'environnement SSL_SRP_USERINFO.

Directive SSLStaplingCache

Description: | Configuration du cache pour l'agrafage OCSP
Syntaxe: | SSLStaplingCache type
Contexte: | configuration du serveur
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Si SSLUseStapling est à "on", cette directive permet de configurer le cache destiné à stocker les réponses OCSP incluses dans la négociation TLS. La configuration d'un cache est obligatoire pour pouvoir utiliser l'agrafage OCSP. A l'exception de none et nonenotnull, cette directive supporte les mêmes types de stockage que la directive SSLSessionCache.

Directive SSLStaplingErrorCacheTimeout

Description: | Durée de vie des réponses invalides dans le cache pour agrafage OCSP
Syntaxe: | SSLStaplingErrorCacheTimeout secondes
Défaut: | SSLStaplingErrorCacheTimeout 600
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Cette directive permet de définir la durée de vie des réponses invalides dans le cache pour agrafage OCSP configuré via la directive SSLStaplingCache. Pour définir la durée de vie des réponses valides, voir la directive SSLStaplingStandardCacheTimeout.

Directive SSLStaplingFakeTryLater

Description: | Génère une réponse "tryLater" pour les requêtes OCSP échouées
Syntaxe: | SSLStaplingFakeTryLater on|off
Défaut: | SSLStaplingFakeTryLater on
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Lorsque cette directive est activée, et si une requête vers un serveur OCSP à des fins d'inclusion dans une négociation TLS échoue, mod_ssl va générer une réponse "tryLater" pour le client (SSLStaplingReturnResponderErrors doit être activée).

Directive SSLStaplingForceURL

Description: | Remplace l'URI du serveur OCSP spécifié dans l'extension AIA du certificat
Syntaxe: | SSLStaplingForceURL uri
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Cette directive permet de remplacer l'URI du serveur OCSP extraite de l'extension authorityInfoAccess (AIA) du certificat. Elle peut s'avérer utile lorsqu'on passe par un mandataire

Directive SSLStaplingResponderTimeout

Description: | Temps d'attente maximum pour les requêtes vers les serveurs OCSP
Syntaxe: | SSLStaplingResponderTimeout secondes
Défaut: | SSLStaplingResponderTimeout 10
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Cette directive permet de définir le temps d'attente maximum lorsque mod_ssl envoie une requête vers un serveur OCSP afin d'obtenir une réponse destinée à être incluse dans les négociations TLS avec les clients (SSLUseStapling doit avoir été activée au préalable).

Directive SSLStaplingResponseMaxAge

Description: | Age maximum autorisé des réponses OCSP incluses dans la négociation TLS
Syntaxe: | SSLStaplingResponseMaxAge secondes
Défaut: | SSLStaplingResponseMaxAge -1
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Cette directive permet de définir l'âge maximum autorisé ("fraîcheur") des réponses OCSP incluses dans la négociation TLS (SSLUseStapling doit avoir été activée au préalable). La valeur par défaut (-1) ne définit aucun âge maximum, ce qui signifie que les réponses OCSP sont considérées comme valides à partir du moment où le contenu de leur champ nextUpdate se trouve dans le futur.

Directive SSLStaplingResponseTimeSkew

Description: | Durée de vie maximale autorisée des réponses OCSP incluses dans la négociation TLS
Syntaxe: | SSLStaplingResponseTimeSkew secondes
Défaut: | SSLStaplingResponseTimeSkew 300
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Cette directive permet de spécifier l'intervalle de temps maximum que mod_ssl va calculer en faisant la différence entre les contenus des champs nextUpdate et thisUpdate des réponses OCSP incluses dans la négociation TLS. Pour pouvoir utiliser cette directive, SSLUseStapling doit être à "on".

Directive SSLStaplingReturnResponderErrors

Description: | Transmet au client les erreurs survenues lors des requêtes OCSP
Syntaxe: | SSLStaplingReturnResponderErrors on|off
Défaut: | SSLStaplingReturnResponderErrors on
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Lorsque cette directive est activée, mod_ssl va transmettre au client les réponses concernant les requêtes OCSP échouées (comme les réponses avec un statut général autre que "successful", les réponses avec un statut de certificat autre que "good", les réponses arrivées à expiration, etc...). Lorsqu'elle est à off, seules les réponses avec un statut de certificat égal à "good" seront incluses dans la négociation TLS.

Directive SSLStaplingStandardCacheTimeout

Description: | Durée de vie des réponses OCSP dans le cache
Syntaxe: | SSLStaplingStandardCacheTimeout secondes
Défaut: | SSLStaplingStandardCacheTimeout 3600
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Cette directive permet de définir la durée de vie des réponses OCSP dans le cache configuré via la directive SSLStaplingCache. Elle ne s'applique qu'aux réponse valides, alors que la directive SSLStaplingErrorCacheTimeout s'applique aux réponses invalides ou non disponibles.

Directive SSLStrictSNIVHostCheck

Description: | Contrôle de l'accès des clients non-SNI à un serveur virtuel à base de nom.
Syntaxe: | SSLStrictSNIVHostCheck on|off
Défaut: | SSLStrictSNIVHostCheck off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible depuis la version 2.2.12 d'Apache

Cette directive permet de contrôler l'accès des clients non-SNI à un serveur virtuel à base de nom. Si elle est définie à on dans le serveur virtuel à base de nom par défaut, les clients non-SNI ne seront autorisés à accéder à aucun serveur virtuel appartenant à cette combinaison IP/port. Par contre, si elle est définie à on dans un serveur virtuel quelconque, les clients non-SNI ne se verront interdire l'accès qu'à ce serveur.

Cette option n'est disponible que si httpd a été compilé avec une version d'OpenSSL supportant SNI.

Exemple

SSLStrictSNIVHostCheck on

Directive SSLUserName

Description: | Nom de la variable servant à déterminer le nom de l'utilisateur
Syntaxe: | SSLUserName nom-var
Contexte: | configuration du serveur, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ssl

Cette variable permet de définir le champ "user" de l'objet de la requête Apache. Ce champ est utilisé par des modules de plus bas niveau pour identifier l'utilisateur avec une chaîne de caractères. En particulier, l'utilisation de cette directive peut provoquer la définition de la variable d'environnement REMOTE_USER. La valeur de l'argument nom-var peut correspondre à toute variable d'environnement SSL.

Notez que cette directive est sans effet si l'option FakeBasicAuth est utilisée (voir SSLOptions).

Exemple

SSLUserName SSL_CLIENT_S_DN_CN

Directive SSLUseStapling

Description: | Active l'ajout des réponses OCSP à la négociation TLS
Syntaxe: | SSLUseStapling on|off
Défaut: | SSLUseStapling off
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_ssl
Compatibilité: | Disponible si on utilise OpenSSL version 0.9.8h ou supérieure

Cette directive permet d'activer l'"Agrafage OCSP" (OCSP stapling) selon la définition de l'extension TLS "Certificate Status Request" fournie dans la RFC 6066. Si elle est activée et si le client le demande, mod_ssl va inclure une réponse OCSP à propos de son propre certificat dans la négociation TLS. Pour pouvoir activer l'Agrafage OCSP, il est nécessaire de configurer un SSLStaplingCache.

L'agrafage OCSP dispense le client de requérir le serveur OCSP directement ; il faut cependant noter que selon les spécifications de la RFC 6066, la réponse CertificateStatus du serveur ne peut inclure une réponse OCSP que pour un seul certificat. Pour les certificats de serveur comportant des certificats de CA intermédiaires dans leur chaîne (c'est un cas typique de nos jours), l'implémentation actuelle de l'agrafage OCSP n'atteint que partiellement l'objectif d' "économie en questions/réponse et en ressources". Pour plus de détails, voir la RFC 6961 (TLS Multiple Certificate Status Extension).

Lorsque l'agrafage OCSP est activé, le mutex ssl-stapling contrôle l'accès au cache de l'agrafage OCSP afin de prévenir toute corruption, et le mutex sss-stapling-refresh contrôle le raffraîchissement des réponses OCSP. Ces mutex peuvent être configurés via la directive Mutex.

Directive SSLVerifyClient

Description: | Niveau de vérification du certificat client
Syntaxe: | SSLVerifyClient niveau
Défaut: | SSLVerifyClient none
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ssl

Cette directive permet de définir le niveau de vérification du certificat pour l'authentification du client. Notez que cette directive peut être utilisée à la fois dans les contextes du serveur principal et du répertoire. Dans le contexte du serveur principal, elle s'applique au processus d'authentification du client utilisé au cours de la négociation SSL standard lors de l'établissement d'une connexion. Dans un contexte de répertoire, elle force une renégociation SSL avec le niveau de vérification du client spécifié, après la lecture d'une requête HTTP, mais avant l'envoi de la réponse HTTP.

Les valeurs de niveau disponibles sont les suivantes :

  • none: aucun certificat client n'est requis
  • optional: le client peut présenter un certificat valide
  • require: le client doit présenter un certificat valide
  • optional_no_ca: le client peut présenter un certificat valide, mais il n'est pas nécessaire que ce dernier soit vérifiable (avec succès). Cette option ne peut pas être utilisée lors de l'authentification du client.

Exemple

SSLVerifyClient require

Directive SSLVerifyDepth

Description: | Profondeur maximale des certificats de CA pour la vérification des certificats clients
Syntaxe: | SSLVerifyDepth nombre
Défaut: | SSLVerifyDepth 1
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | AuthConfig
Statut: | Extension
Module: | mod_ssl

Cette directive permet de spécifier la profondeur maximale à laquelle mod_ssl va effectuer sa vérification avant de décider que le client ne possède pas de certificat valide. Notez que cette directive peut être utilisée à la fois dans les contextes du serveur principal et de répertoire. Dans le contexte du serveur principal, elle s'applique au processus d'authentification du client utilisé au cours de la négociation SSL standard lors de l'établissement d'une connexion. Dans un contexte de répertoire, elle force une renégociation SSL avec le client selon la nouvelle profondeur spécifiée, après la lecture d'une requête HTTP, mais avant l'envoi de la réponse HTTP.

La profondeur correspond au nombre maximum de fournisseurs de certificats intermédiaires, c'est à dire le nombre maximum de certificats de CA que l'on est autorisé à suivre lors de la vérification du certificat du client. Une profondeur de 0 signifie que seuls les certificats clients auto-signés sont acceptés ; la profondeur par défaut de 1 signifie que le certificat client peut être soit auto-signé, soit signé par une CA connue directement du serveur (c'est à dire que le certificat de la CA doit être référencé par la directive SSLCACertificatePath), etc...

Exemple

SSLVerifyDepth 10


mod_status - Serveur Apache HTTP Version 2.4

Module Apache mod_status

Description: | Fournit des informations sur les performances et l'activité du serveur
Statut: | Base
Identificateur de Module: | status_module
Fichier Source: | mod_status.c

Sommaire

Le module Status permet à un administrateur de déterminer le niveau de performances de son serveur. Les statistiques instantanées du serveur sont présentées dans une page HTML sous une forme aisément lisible. Si nécessaire, cette page peut être configurée pour être automatiquement actualisée (sous réserve de compatibilité du navigateur). Une autre page fournit l'état instantané du serveur sous la forme d'une simple liste lisible par une machine.

Les détails fournis sont :

  • Le nombre de processus servant les requêtes
  • Le nombre de processus inactifs
  • L'état de chaque processus, le nombre de requêtes qu'il a traitées et le nombre total d'octets qu'il a servis (*)
  • Le nombre total d'accès effectués et d'octets servis (*)
  • Le moment où le serveur a été démarré/redémarré et le temps écoulé depuis
  • Les valeurs moyennes du nombre de requêtes par seconde, du nombre d'octets servis par seconde et du nombre d'octets par requête (*)
  • Le pourcentage CPU instantané utilisé par chaque processus et par l'ensemble des processus (*)
  • Les hôtes et requêtes actuellement en cours de traitement (*)

Les lignes se terminant par "(*)" ne sont disponibles que si la directive ExtendedStatus est définie à On. Depuis la version 2.3.6, le chargement de mod_status définit automatiquement ExtendedStatus à On.

Activation du rapport d'état

Pour n'activer les rapports d'état que pour les navigateurs appartenent au domaine example.com, ajoutez ces lignes à votre fichier de configuration httpd.conf :

<Location "/etat-serveur">
    SetHandler server-status
    Require host example.com
</Location>

Il est alors possible d'obtenir les statistiques du serveur en utilisant un navigateur web et en accédant à la page http://votre.serveur/etat-serveur.

Actualisation automatique

Vous pouvez faire en sorte que cette page d'état s'actualise elle-même automatiquement si votre navigateur supporte "refresh". Pour ce faire, accédez à la page http://votre.serveur/etat-serveur?refresh=N, pour que cette dernière soit actualisée toutes les N secondes.

Fichier d'état lisible par une machine

La page http://votre.serveur/etat-serveur?auto permet d'obtenir une version du fichier d'état lisible par une machine. Ceci s'avère intéressant dans le cadre d'une exécution automatique : voir le programme en Perl log_server_status situé dans le répertoire /support de votre distribution du serveur HTTP Apache.

Veuillez noter que si mod_status a été chargé dans le serveur, son gestionnaire sera disponible dans tous les fichiers de configuration, y compris les fichiers de configuration de niveau répertoire (par exemple .htaccess), ce qui peut avoir des répercutions quant à la sécurité de votre site.

Utilisation de server-status pour la recherche de défauts de fonctionnement

La page server-status peut servir de point de départ à la recherche de défauts de fonctionnement lorsque votre serveur mobilise toutes les ressources disponibles (CPU ou mémoire), pour identifier quels clients ou requêtes sont la cause du problème.

Tout d'abord, assurez-vous que la directive ExtendedStatus est bien définie à on, de façon à ce que vous puissiez avoir accès à toutes les informations à propos de la requête et du client pour chaque processus enfant ou thread.

Consultez ensuite la liste des processus en cours (à l'aide de top, ou d'un utilitaire de listage des processus similaire), afin d'identifier les processus coupables. Triez l'affichage de top par utilisation CPU ou mémoire, en fonction du problème rencontré.

Rechargez la page server-status et recherchez les identifiants des processus trouvés précédemment ; vous pourrez alors déterminer quelle requête est traitée par ces processus, pour quel client. Les requêtes peuvent apparaître de manière fugitive, et il se peut que vous deviez effectuer plusieurs essais avant de parvenir à les prendre en flagrant délit, pour ainsi dire.

Cette procédure devrait vous permettre de cerner quel client, ou type de requête, sont à l'origine de vos problèmes de charge. Il est probable que vous identifiiez une application web au comportement anormal, ou un client en train d'attaquer votre site.


mod_substitute - Serveur Apache HTTP Version 2.4

Module Apache mod_substitute

Description: | Effectue des opérations de recherche/remplacement sur les corps de réponses
Statut: | Extension
Identificateur de Module: | substitute_module
Fichier Source: | mod_substitute.c
Compatibilité: | Disponible depuis la version 2.2.7 du serveur HTTP Apache

Sommaire

mod_substitute fournit un mécanisme permettant d'effectuer des substitutions de chaînes fixes ou d'expressions rationnelles sur les corps de réponses.

Directive Substitute

Description: | Modèle de substition dans le contenu de la réponse
Syntaxe: | Substitute s/modèle/substitution/[infq]
Contexte: | répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_substitute

La directive Substitute permet de spécifier un modèle de recherche/remplacement à appliquer au corps de la réponse.

La signification du modèle peut être modifiée via toute combinaison de ces drapeaux :

i
Effectue une comparaison sans tenir compte de la casse.
n
Par défaut, le modèle est traité en tant qu'expression rationnelle. Le drapeau n force le traitement du modèle en tant que chaîne fixe.
f
Avec le drapeau f, mod_substitute met à plat le résultat d'une substitution (les conteneurs ou buckets ne sont pas dissociés), ce qui permet à d'éventuelles substitutions ultérieures de s'effectuer sur cette dernière. C'est le comportement par défaut.
q
Avec le drapeau q, mod_substitute dissocie les conteneurs (ou buckets) après chaque substitution. Ceci peut améliorer la rapidité de la réponse et diminuer la quantité de mémoire utilisée, mais ne doit être utilisé que s'il n'existe aucune possibilité pour que le résultat d'une substitution ne corresponde au modèle ou à l'expression rationnelle d'une substitution ultérieure.

substitution peut contenir du texte et des références arrières d'expressions rationnelles.

Exemple

<Location "/>
    AddOutputFilterByType SUBSTITUTE text/html
    Substitute "s/foo/bar/ni"
</Location>

Le caractère utilisé pour séparer (ou "délimiter") les différentes partie de la valeur de substitution est référencé sous le nom de "délimiteur", et il s'agit le plus souvent d'un "slash".

Si le modèle ou la chaîne de substitution contient un caractère slash '/', il est possible d'utiliser un autre délimiteur afin de rendre la directive plus lisible :

Exemple d'utilisation d'un délimiteur alternatif

<Location "/">
    AddOutputFilterByType SUBSTITUTE text/html
    Substitute "s|<BR */?>|<br />|i"
</Location>

Lorsqu'on utilise des expressions rationnelles, on peut insérer des références arrières dans les opérations de comparaison et de substitution, comme illustré dans l'exemple suivant :

Exemple d'utilisation de références arrières et de captures

<Location "/">
    AddOutputFilterByType SUBSTITUTE text/html
    # "foo=k,bar=k" -> "foo/bar=k"
    Substitute "s|foo=(\w+),bar=\1|foo/bar=$1|"
</Location>

Un scénario courant d'utilisation de mod_substitute est la situation où un serveur frontal mandate des requêtes pour un serveur d'arrière-plan qui renvoie des documents HTML contenant des URLs intégrées codées en dur qui font référence à ce serveur d'arrière-plan. Ces URLs ne fonctionnent pas pour l'utilisateur final car le serveur d'arrière-plan est hors d'atteinte.

On peut, dans ce cas, utiliser mod_substitute pour réécrire ces URLs afin qu'elles soit utilisables dans la partie située derrière le mandataire :

Réécriture des URLs intégrées à un contenu mandaté

ProxyPass        "/blog/" "http://internal.blog.example.com/"
ProxyPassReverse "/blog/" "http://internal.blog.example.com/"

Substitute "s|http://internal.blog.example.com/|http://www.example.com/blog/|i"

La directive ProxyPassReverse modifie tout en-tête Location (redirection) envoyé par le serveur d'arrière-plan et, dans cet exemple, la directive Substitute se charge à son tour de la modification de la réponse HTML.

Directive SubstituteInheritBefore

Description: | Modifie l'ordre de fusion des modèles hérités
Syntaxe: | SubstituteInheritBefore on|off
Défaut: | SubstituteInheritBefore on
Contexte: | répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_substitute
Compatibilité: | Disponible à partir de la version 2.4.17 du serveur HTTP Apache

Cette directive permet de définir si l'on applique les modèles Substitute hérités en premier (valeur on), ou après ceux du contexte courant (valeur off). La valeur de la directive SubstituteInheritBefore est elle-même héritée, et les contextes qui en héritent (ceux qui ne définissent pas explicitement leur propre directive SubstituteInheritBefore) appliqueront donc l'ordre de fusion défini le plus proche.

Directive SubstituteMaxLineLength

Description: | Définit la longueur de ligne maximale
Syntaxe: | SubstituteMaxLineLength octets(b|B|k|K|m|M|g|G)
Défaut: | SubstituteMaxLineLength 1m
Contexte: | répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_substitute
Compatibilité: | Disponible à partir de la version 2.4.11 du serveur HTTP Apache

La taille de la ligne traitée par mod_substitute est limitée afin de restreindre l'utilisation des ressources mémoire. La directive SubstituteMaxLineLength permet de définir cette limite. La valeur de la limite peut être spécifiée sous la forme d'un nombre d'octets, et peut être suffixée par une des lettres b, B, k, K, m, M, g ou G pour fournir une valeur respectivement en octets, kiloOctets, mégaOctets ou gigaOctets.

Example

<Location "/">
    AddOutputFilterByType SUBSTITUTE text/html
    SubstituteMaxLineLength 10m
    Substitute "s/foo/bar/ni"
</Location>


mod_suexec - Serveur Apache HTTP Version 2.4

Module Apache mod_suexec

Description: | Permet l'exécution des scripts CGI sous l'utilisateur et le groupe spécifiés
Statut: | Extension
Identificateur de Module: | suexec_module
Fichier Source: | mod_suexec.c

Sommaire

Ce module, en combinaison avec son programme support suexec, permet l'exécution des scripts CGI sous l'utilisateur et le groupe spécifiés.

Traitement des bugs

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

Voir aussi

  • Support de SuEXEC

Directive SuexecUserGroup

Description: | L'utilisateur et le groupe sous lesquels les programmes CGI doivent s'exécuter
Syntaxe: | SuexecUserGroup Utilisateur Groupe
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_suexec

La directive SuexecUserGroup permet de spécifier l'utilisateur et le groupe sous lesquels les programmes CGI doivent s'exécuter. Les requêtes non CGI seront toujours traitées avec l'utilisateur spécifié par la directive User.

Exemple

SuexecUserGroup nobody nogroup

Le démarrage échouera si cette directive est spécifiée et si la fonctionnalité suEXEC est désactivée.

Voir aussi

  • Suexec


mod_unique_id - Serveur Apache HTTP Version 2.4

Module Apache mod_unique_id

Description: | Fournit une variable d'environnement contenant un identifiant unique pour chaque requête
Statut: | Extension
Identificateur de Module: | unique_id_module
Fichier Source: | mod_unique_id.c

Sommaire

Ce module fournit un identifiant dont l'unicité est garantie parmi "toutes" les requêtes sous des conditions très précises. L'identifiant unique le sera aussi parmi plusieurs machines appartenant à un cluster correctement configuré. L'identifiant est affecté à la variable d'environnement UNIQUE_ID pour chaque requête. Les identifiants uniques sont utiles pour diverses raisons dont la nature se situe au delà de la portée de ce document.

Théorie

Tout d'abord un bref rappel de la manière dont le serveur Apache fonctionne sous Unix (cette fonctionnalité n'étant actuellement pas supportée sous Windows NT). Sous Unix, Apache crée plusieurs processus enfants, ces derniers traitant les requêtes une par une. Chaque processus enfant peut traiter plusieurs requêtes pendant sa durée de vie. Dans le cadre de cette discussion, nous supposerons que les différents processus enfants ne s'échangent pas de données entre eux. Nous nous référerons aux processus enfants sous le nom de processus httpd.

Votre site web est réparti entre une ou plusieurs machines dont vous êtes l'administrateur, et que nous nommerons cluster de serveurs. Chaque serveur peut exécuter plusieurs instances d'Apache. L'ensemble de ces dernières sera considéré comme "l'Univers", et sous certaines hypothèses, nous montrerons qu'il est possible dans cet univers, de générer des identifiants uniques pour chaque requête, sans pour autant nécessiter une communication importante entre les différents serveurs du cluster.

Les machines de votre cluster doivent satisfaire ces conditions (même si le cluster ne comporte qu'une machine, vous devez synchroniser son horloge avec NTP) :

  • Les temps des machines sont synchronisés via NTP ou tout autre protocole de synchronisation du temps en réseau.
  • Les nom d'hôtes des machines sont tous différents, de façon à ce que le module puisse recevoir une adresse IP différente pour chaque machine du cluster en effectuant une recherche sur le nom d'hôte.

Au vu des caractéristiques actuelles du système d'exploitation, nous supposerons que les pids (identifiants processus) sont codés sur 32 bits. Si le système d'exploitation utilise plus de 32 bits pour un pid, la correction est triviale mais doit être effectuée dans le code.

Ces hypothèses posées, à un instant donné, nous pouvons distinguer tout processus httpd sur toute machine du cluster de tous les autres processus httpd. Pour ce faire, il suffit d'utiliser l'adresse IP de la machine et le pid du processus httpd. Un processus httpd peut traiter plusieurs requêtes simultanément si vous utilisez un module MPM multi-threadé. Pour identifier les threads, Apache httpd utilise en interne un index de threads. Ainsi, afin de générer des identifiants uniques pour chaque requête, il suffit d'effectuer une distinction en fonction du temps.

Pour déterminer le temps, nous utiliserons un repère de temps Unix (les secondes écoulées depuis le 1er janvier 1970 UTC), et un compteur 16 bits. La précision du repère de temps n'étant que d'une seconde, le compteur va représenter 65536 valeurs par seconde. Le quadruplet (adresse IP, pid, repère de temps, compteur) est en mesure de distinguer 65536 requêtes par seconde par processus httpd. Il peut cependant arriver que le même pid soit réutilisé au cours du temps, et le compteur est là pour pallier cet inconvénient.

Lorsqu'un processus enfant httpd est créé, le compteur est initialisé avec (nombre de microsecondes actuel divisé par 10) modulo 65536 (cette formule a été choisie pour éliminer certains problème de variance avec les bits de poids faibles du compteur de microsecondes sur certains systèmes). Lorsqu'un identifiant unique est généré, le repère de temps utilisé est le moment où la requête arrive sur le serveur web. Le compteur est incrémenté à chaque création d'identifiant (et peut repasser à 0 lorsqu'il a atteint sa valeur maximale).

Le noyau génère un pid pour chaque processus lors de sa création, et le compteur de pid est réinitialisé à une certaine valeur lorsqu'il a atteint sa valeur maximale (les pid sont codés sur 16 bits sous de nombreux Unixes, mais les systèmes les plus récents les ont étendus à 32 bits). La même valeur de pid pourra donc être réutilisée au cours du temps. Cependant, tant qu'elle n'est pas réutilisée dans la même seconde, elle ne remet pas en cause l'unicité de notre quadruplet. Nous supposerons donc que le système ne créera pas plus de 65536 processus en une seconde (ce nombre peut être de 32768 sous certains Unixes, mais même dans ce cas, on est en général loin de cette situation).

Il est possible que le temps se répète pour une raison quelconque. Supposons par exemple que l'horloge système soit retardée et repasse par un temps passé (ou bien, comme elle avançait, elle a été remise à l'heure, et elle repasse par un temps futur). Dans ce cas, il peut être facilement démontré que le couple pid/repère de temps peut être réutilisé. Le choix de la formule d'initialisation du compteur a été effectué dans l'intention de pallier ce problème. Notez qu'un nombre vraiment aléatoire serait souhaitable pour initialiser le compteur, mais il n'existe pas de tel nombre directement lisible sur la plupart des systèmes (c'est à dire que vous ne pouvez pas utiliser rand() car vous devez déclencher le générateur avec une valeur unique, et vous ne pouvez pas utiliser le temps à cet effet car celui-ci , au moins à la seconde près, s'est répété). Il ne s'agit donc pas d'une défense parfaite.

Même si elle n'est pas parfaite, quel est le degré d'efficacité de cette défense ? Supposons qu'une de vos machines serve au plus 500 requêtes par seconde (ce qui constitue une limite supérieure très raisonnable au moment où ce document est écrit, car les systèmes ne se contentent en général pas de débiter des fichiers statiques). Pour y parvenir, un certain nombre de processus enfants sera nécessaire, qui dépendra du nombre de clients simultanés présents. Mais soyons pessimiste et supposons qu'un seul processus enfant soit capable de servir 500 requêtes par secondes. Il existe 1000 valeurs de démarrage possibles du compteur pour lesquelles deux séquences de 500 requêtes puissent se recouvrir. Il y a donc 1,5% de chance que le processus enfant répète une valeur de compteur si le temps se répète (avec une résolution d'une seconde), et l'unicité sera alors remise en cause. C'est cependant un exemple très pessimiste, et avec les valeurs du monde réel, il y a bien moins de chances que cela ne se produise. Si vous estimez que ceci a tout de même quelque chances de se produire sur votre système, vous pouvez migrer vers un compteur à 32 bits (en modifiant le code).

On pourrait supposer que ceci a plus de chance de se produire lors du passage à l'heure d'hiver où l'horloge est "retardée". Cela ne constitue cependant pas un problème car les temps pris en compte ici sont des temps UTC, qui vont "toujours" de l'avant. Notez que les Unixes à base de processeur x86 peuvent nécessiter une configuration particulière pour que ceci soit vrai -- il doivent être configurés pour assumer que l'horloge système est en UTC et compenser de manière appropriée. Mais même dans ce cas, si vous utilisez NTP, votre temps UTC sera correct peu après le redémarrage.

La variable d'environnement UNIQUE_ID est construite par codage du quadruplet de 144 bits (adresse IP sur 32 bits, pid sur 32 bits, repère de temps sur 32 bits, compteur 16 bits et index de threads sur 32 bits) en utilisant l'alphabet [A-Za-z0-9@-] d'une manière similaire à celle du codage MIME base64, et sa valeur se présente sous la forme d'une chaîne de 24 caractères. L'alphabet MIME base64 est en fait [A-Za-z0-9+/] ; cependant, les caractères + et / nécessitent un codage particulier dans les URLs, ce qui rend leur utilisation peu commode. Toutes les valeurs sont codées dans l'ordre des octets d'une adresse réseau de façon à ce que le codage soit comparable entre des architectures où l'ordre des octets est différent. L'ordre réel de codage est : repère de temps, adresse IP, pid, compteur. Cet ordre de codage possède un but précis, mais il faut souligner que les applications n'ont aucun intérêt à entrer dans les détails de ce codage. Les applications doivent se contenter de traiter la variable UNIQUE_ID comme un symbole opaque, qui peut être comparé avec d'autres UNIQUE_IDs en ne testant que leur égalité.

L'ordre a été choisi de façon à ce qu'il soit possible de modifier le codage dans le futur sans avoir à se préoccuper de conflits éventuels avec une base de données de UNIQUE_IDs existante. Les nouveaux codages doivent conserver le repère de temps comme premier élément, et pour le reste, utiliser les même alphabet et longueur en bits. Comme les repères de temps constituent essentiellement un séquence croissante, il suffit que toutes les machines du cluster arrêtent de traiter toute requête dans la même seconde repère, et n'utilisent alors plus l'ancien format de codage. Ensuite, elles peuvent reprendre le traitement des requêtes en utilisant les nouveaux codages.

Nous pensons que ceci apporte une solution relativement portable au problème. Les identifiants générés possèdent une durée de vie pratiquement infinie car les identifiants futurs pourront être allongés selon les besoins. Pratiquement aucune communication n'est requise entre les machines du cluster (seule la synchronisation NTP est requise, ce qui représente une charge très faible), et aucune communication entre les processus httpd n'est nécessaire (la communication est implicite et incluse dans le pid assigné par le noyau). Dans des situations très spécifiques, l'identifiant peut être raccourci, mais dans ce cas, d'avantage d'informations doivent être admises (par exemple, les 32 bits de l'adresse IP sont excessifs pour la plupart des sites, mais il n'existe pas de valeur de remplacement portable plus courte).


mod_userdir - Serveur Apache HTTP Version 2.4

Module Apache mod_userdir

Description: | Répertoires propres à un utilisateur
Statut: | Base
Identificateur de Module: | userdir_module
Fichier Source: | mod_userdir.c

Sommaire

Ce module permet l'accès aux répertoires propres à un utilisateur en utilisant la syntaxe http://example.com/~utilisateur/.

Traitement des bugs

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

Voir aussi

  • Mise en correspondance des URLs avec le système de fichiers
  • Tutoriel public_html

Directive UserDir

Description: | Chemin des répertoires propres à un utilisateur
Syntaxe: | UserDir nom-répertoire [nom-répertoire] ...
Contexte: | configuration du serveur, serveur virtuel
Statut: | Base
Module: | mod_userdir

La directive UserDir permet de définir le répertoire réel du répertoire home d'un utilisateur à utiliser à la réception d'une requête pour un document de cet utilisateur. nom-répertoire peut se présenter sous la forme suivante :

  • Le nom d'un répertoire ou un modèle tel que ceux présentés ci-dessous.
  • Le mot-clé disabled. Toutes les traductions nom d'utilisateur vers répertoire sont alors désactivées, à l'exception de celles comportant le mot-clé enabled (voir ci-dessous).
  • Le mot-clé disabled suivi d'une liste de noms d'utilisateurs séparés par des espaces. Les noms d'utilisateurs apparaissant dans une telle liste ne feront jamais l'objet d'une traduction vers un répertoire, même dans le cas où ils apparaîtront dans une clause enabled.
  • Le mot-clé enabled suivi d'une liste de noms d'utilisateurs séparés par des espaces. Les noms d'utilisateurs apparaissant dans une telle liste seront traduits en répertoires même dans le cas où une clause disable globale est active, mais pas s'ils apparaissent aussi dans une clause disabled.

Si aucun mot-clé enabled ou disabled n'apparait dans la directive Userdir, l'argument est traité en tant que modèle de fichier, et utilisé pour traduire le nom d'utilisateur en une spécification de répertoire. Une requête pour http://www.example.com/~bob/un/deux.html sera traduite en :

Directive Userdir utilisée | Chemin traduit
UserDir public_html | ~bob/public_html/un/deux.html
UserDir /usr/web | /usr/web/bob/un/deux.html
UserDir /home/*/www | /home/bob/www/un/deux.html

Les directives suivantes vont envoyer des redirections au client :

Directive Userdir utilisée | Chemin traduit
UserDir http://www.example.com/utilisateurs | http://www.example.com/utilisateurs/bob/un/deux.html
UserDir http://www.example.com/*/usr | http://www.example.com/bob/usr/un/deux.html
UserDir http://www.example.com/~*/ | http://www.example.com/~bob/un/deux.html
Soyez prudent avec cette directive ; par exemple, "UserDir ./" ferait correspondre "/~root" à "/" - ce qui n'est probablement pas souhaité. Il est fortement recommandé d'inclure une déclaration "UserDir disabled root" dans votre configuration. Voir aussi la directive Directory et la page Conseils en matière de sécurité pour plus d'informations.

Exemples supplémentaires :

Pour permettre à quelques utilisateurs et seulement à ceux-ci de posséder des répertoires UserDir, utilisez la configuration suivante :

UserDir disabled
UserDir enabled user1 user2 user3

Pour permettre à la plupart des utilisateurs de posséder des répertoires UserDir, mais l'interdire à quelques uns, utilisez la configuration suivante :

UserDir disabled utilisateur4 utilisateur5 utilisateur6

Il est aussi possible de spécifier des répertoires utilisateurs alternatifs. Si vous utilisez une commande comme :

UserDir "public_html" "/usr/web" "http://www.example.com/"

Avec une requête pour http://www.example.com/~bob/un/deux.html, le serveur tentera tout d'abord de trouver la page à ~bob/public_html/un/deux.html, puis à /usr/web/bob/un/deux.html, et enfin il enverra une redirection vers http://www.example.com/bob/un/deux.html.

Si vous spécifiez une redirection, elle doit être la dernière alternative de la liste. Apache httpd ne pouvant pas déterminer si la redirection a réussi, si cette dernière ne se trouve pas en fin de liste, c'est cette alternative qui sera toujours utilisée.

La substitution de répertoire utilisateur n'est pas activée par défaut depuis la version 2.1.4. Dans les versions précédentes, UserDir public_html était sous-entendu si aucune directive UserDir n'était présente.

Détails à propos de la fusion

Lorsqu'on passe du contexte global au contexte de serveur virtuel, les listes d'utilisateurs spécifiques activés ou désactivés sont remplacées par les listes du contexte, et non fusionnées.

Voir aussi

  • Tutoriel sur les répertoires web utilisateur


mod_usertrack - Serveur Apache HTTP Version 2.4

Module Apache mod_usertrack

Description: | Journalisation Clickstream des liens parcourus par un utilisateur sur un site
Statut: | Extension
Identificateur de Module: | usertrack_module
Fichier Source: | mod_usertrack.c

Sommaire

Ce module permet de suivre le parcours d'un utilisateur à travers votre site web en faisant appel aux cookies de navigateur.

Journalisation

mod_usertrack définit un cookie qui peut être journalisé via les formats configurables du module mod_log_config :

LogFormat "%{Apache}n %r %t" usertrack
CustomLog logs/clickstream.log usertrack

Directive CookieDomain

Description: | Le domaine auquel le cookie traceur s'applique
Syntaxe: | CookieDomain domaine
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_usertrack

Cette directive permet de définir le domaine auquel le cookie traceur s'applique. Si elle n'est pas présente, aucun domaine n'est inclus dans le champ d'en-tête cookie.

La chaîne dommaine doit commencer par un point, et doit comporter au moins un point entouré d'autres caractères. Par exemple, .example.com est une chaîne valide, mais www.example.com et .com ne le sont pas.

La plupart des navigateurs utilisés actuellement n'autorisent pas la définition de cookies pour un domaine racine de deux niveaux, tel que .co.uk, bien qu'un tel domaine remplisse les conditions de validité décrites ci-dessus.
Ces domaines sont équivalents à des domaines racines comme .com, et autoriser de tels cookies peut constituer un risque en matière de sécurité. Ainsi, si vous vous situez sous un domaine racine de deux niveaux, vous devez encore utiliser votre domaine véritable, comme vous le feriez avec tout autre domaine racine (par exemple .example.co.uk).
CookieDomain .example.com

Directive CookieExpires

Description: | Durée avant expiration du cookie traceur
Syntaxe: | CookieExpires durée
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_usertrack

Lorsqu'elle est utilisée, cette directive définit une durée avant l'expiration du cookie généré par le module usertrack. La durée peut être spécifiée sous la forme d'un nombre de secondes, ou sous une forme du style "2 weeks 3 days 7 hours". les termes valides sont : years, months, weeks, days, hours, minutes et seconds. Si la durée est spécifiée dans un format autre qu'un nombre de secondes, elle doit être entourée de guillemets.

Si cette directive est absente, la durée de vie des cookies est limitée à la session actuelle du navigateur.

CookieExpires "3 weeks"

Directive CookieName

Description: | Nom du cookie traceur
Syntaxe: | CookieName symbole
Défaut: | CookieName Apache
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_usertrack

Cette directive vous permet de modifier le nom du cookie que ce module utilise pour sa journalisation. Le nom par défaut du cookie est "Apache".

Vous devez spécifier un nom de cookie valide ; les résultats sont imprévisibles si vous utilisez un nom contenant des caractères inhabituels. Les caractères valides font partie des intervales A-Z, a-z, 0-9, "_", et "-".

CookieName clicktrack

Directive CookieStyle

Description: | Format du champ d'en-tête cookie
Syntaxe: | CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965
Défaut: | CookieStyle Netscape
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_usertrack

Cette directive permet de contrôler le format du champ d'en-tête cookie. Les trois formats autorisés sont :

  • Netscape : il s'agit du format original, mais est désormais obsolète. C'est le format par défaut et il correspond à la syntaxe historique utilisée par Apache.
  • Cookie ou RFC2109 : c'est la syntaxe qui remplace la syntaxe Netscape.
  • Cookie2 ou RFC2965 : c'est la syntaxe de cookie la plus actuelle.

Tous les clients ne supportent pas l'ensemble de ces formats, mais il est conseillé d'utiliser le plus récent qui sera en général supporté par le navigateur utilisé par vos utilisateurs. A l'heure où ce document est écrit, la plupart des navigateurs supportent ces trois formats, Cookie2 étant le format recommandé.

CookieStyle Cookie2

Directive CookieTracking

Description: | Active le cookie traceur
Syntaxe: | CookieTracking on|off
Défaut: | CookieTracking off
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride: | FileInfo
Statut: | Extension
Module: | mod_usertrack

Lorsque le module mod_usertrack est chargé, et si CookieTracking on est définie, Apache enverra un cookie traceur pour toute nouvelle requête. Cette directive peut être utilisée pour activer ou désactiver ce comportement pour un serveur virtuel ou un répertoire. Par défaut, l'activation de mod_usertrack ne suffit pas pour activer les cookies.

CookieTracking on


mod_version - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_version

Description: | Version dependent configuration
Status: | Extension
Module Identifier: | version_module
Source File: | mod_version.c

Summary

This module is designed for the use in test suites and large networks which have to deal with different httpd versions and different configurations. It provides a new container -- <IfVersion>, which allows a flexible version checking including numeric comparisons and regular expressions.

Examples

<IfVersion 2.4.2>
    # current httpd version is exactly 2.4.2
</IfVersion>

<IfVersion >= 2.5>
    # use really new features :-)
</IfVersion>

See below for further possibilities.

<IfVersion> Directive

Description: | contains version dependent configuration
Syntax: | <IfVersion [[!]operator] version> ... </IfVersion>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Extension
Module: | mod_version

The <IfVersion> section encloses configuration directives which are executed only if the httpd version matches the desired criteria. For normal (numeric) comparisons the version argument has the format major[.minor[.patch]], e.g. 2.1.0 or 2.2. minor and patch are optional. If these numbers are omitted, they are assumed to be zero. The following numerical operators are possible:

operator | description
= or == | httpd version is equal
> | httpd version is greater than
>= | httpd version is greater or equal
< | httpd version is less than
<= | httpd version is less or equal

Example

<IfVersion >= 2.3>
    # this happens only in versions greater or
    # equal 2.3.0.
</IfVersion>

Besides the numerical comparison it is possible to match a regular expression against the httpd version. There are two ways to write it:

operator | description
= or == | version has the form /regex/
~ | version has the form regex

Example

<IfVersion = /^2.4.[01234]$/>
    # e.g. workaround for buggy versions
</IfVersion>

In order to reverse the meaning, all operators can be preceded by an exclamation mark (!):

<IfVersion !~ ^2.4.[01234]$>
    # not for those versions
</IfVersion>

If the operator is omitted, it is assumed to be =.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_vhost_alias - Serveur Apache HTTP Version 2.4

Module Apache mod_vhost_alias

Description: | Permet de configurer dynamiquement l'hébergement virtuel de masse
Statut: | Extension
Identificateur de Module: | vhost_alias_module
Fichier Source: | mod_vhost_alias.c

Sommaire

Ce module permet de créer des serveurs virtuels configurés dynamiquement, en autorisant l'utilisation de l'adresse IP et/ou de l'en-tête Host: de la requête HTTP comme partie du nom de chemin afin de déterminer les fichiers à servir. Ceci facilite la gestion d'un grand nombre de serveurs virtuels possèdant des configurations similaires.

Note

Si les modules mod_alias ou mod_userdir sont utilisés pour traduire les URIs en noms de fichiers, ils l'emportent sur les directives du module mod_vhost_alias décrites ci-dessous. Par exemple, la configuration suivante fera correspondre /cgi-bin/script.pl à /usr/local/apache2/cgi-bin/script.pl dans tous les cas :

ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"
VirtualScriptAlias "/never/found/%0/cgi-bin/"

Traitement des bugs

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

Voir aussi

  • UseCanonicalName
  • Configuration dynamique de l'hébergement virtuel de masse

Interpolation du nom de répertoire

Toutes les directives de ce module insèrent une chaîne dans un nom de chemin. La chaîne insérée (que nous appellerons maintenant le "nom") peut être soit le nom du serveur (voir la directive UseCanonicalName pour les détails sur la manière dont il est déterminé), soit l'adresse IP du serveur virtuel hébergé par le serveur sous la forme d'un quadruplet d'octets séparés par des points. L'insertion est contrôlée par des spécificateurs inspirés de printf et possèdant de nombreux formats :

%% | insère un %
%p | insère le numéro de port du serveur virtuel
%N.M | insère le nom (en partie)

N et M permettent de spécifier des sous-chaînes du nom. N sélectionne un des composants du nom séparés par des points, et M sélectionne des caractères à l'intérieur de ce que N a sélectionné. M est optionnel et sa valeur par défaut est 0 s'il n'est pas spécifié ; le point doit être présent si et seulement si M l'est aussi. Les modes d'insertion sont les suivants :

0 | le nom en entier
1 | la première partie
2 | la seconde partie
-1 | la dernière partie
-2 | l'avant-dernière partie
2+ | toutes les parties à partir de la seconde
-2+ | toutes les parties jusqu'à l'avant-dernière
1+ et -1+ | identique à 0

Si N ou M est plus grand que le nombre de parties disponibles, seul un caractère de soulignement est inséré.

Exemples

Pour des serveurs virtuels simples à base de nom, utilisez les directives suivantes dans le fichier de configuration de votre serveur :

UseCanonicalName    Off
VirtualDocumentRoot "/usr/local/apache/vhosts/%0"

Une requête pour http://www.example.com/repertoire/fichier.html concernera alors la ressource /usr/local/apache/vhosts/www.example.com/repertoire/fichier.html.

Pour un très grand nombre de serveurs virtuels, il est avantageux d'organiser les fichiers de façon à réduire la taille du répertoire vhosts. Pour ce faire, insérez les lignes suivantes dans votre fichier de configuration :

UseCanonicalName    Off
VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2"

Une requête pour http://www.domaine.example.com/repertoire/fichier.html concernera alors la ressource /usr/local/apache/vhosts/example.com/d/o/m/domaine/repertoire/fichier.html.

Une répartition plus régulière des fichiers peut être obtenue en partant de la fin d'un composant du nom, comme dans l'exemple suivant :

VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2"

La requête précédente concernerait alors /usr/local/apache/vhosts/example.com/e/n/i/domaine/repertoire/fichier.html.

Vous pouvez également utiliser :

VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+"

La requête précédente concernerait alors /usr/local/apache/vhosts/example.com/d/o/m/aine/repertoire/fichier.html.

Une demande très courante des utilisateurs concerne la possibilité de faire correspondre plusieurs racines de documents à plusieurs domaines, sans avoir à se préoccuper de la longueur ou du nombre de parties du nom d'hôte faisant partie de la requête. Si le nom d'hôte de la requête est sub.www.domain.example.com au lieu de simplement www.domain.example.com, alors en utilisant %3+, la racine des documents sera /usr/local/apache/vhosts/domain.example.com/... au lieu du répertoire example.com attendu. Dans ce genre de situation, il peut s'avérer préférable d'utiliser la combinaison %-2.0.%-1.0 qui fournira toujours le nom de domaine et le tld, par exemple example.com sans tenir compte du nombre de sous-domaines ajoutés au nom d'hôte. Dans ces conditions, il est possible d'élaborer une configuration qui associera les sous-domaines de premier, second et troisième niveau au même répertoire :

VirtualDocumentRoot "/usr/local/apache/vhosts/%-2.0.%-1.0"

Dans l'exemple ci-dessus, www.example.com, www.sub.example.com ou example.com correspondront tous au répertoire /usr/local/apache/vhosts/example.com.

Pour l'hébergement virtuel à base d'adresse IP, vous pouvez insérer les lignes suivantes dans votre fichier de configuration :

UseCanonicalName DNS
VirtualDocumentRootIP "/usr/local/apache/vhosts/%1/%2/%3/%4/docs"
VirtualScriptAliasIP  "/usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin"

Si l'adresse IP de www.domaine.example.com est 10.20.30.40, une requête pour http://www.domaine.example.com/repertoire/fichier.html concernera la ressource /usr/local/apache/vhosts/10/20/30/40/docs/repertoire/fichier.html. Une requête pour http://www.domaine.example.com/cgi-bin/script.pl concernera la ressource /usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl.

Si vous voulez insérer le caractère . dans une directive VirtualDocumentRoot, et si cela crée un conflit avec un spécificateur %, vous pouvez contourner le problème de la manière suivante :

VirtualDocumentRoot "/usr/local/apache/vhosts/%2.0.%3.0"

Une requête pour http://www.domaine.example.com/repertoire/fichier.html concernera alors la ressource /usr/local/apache/vhosts/domaine.exemple/repertoire/fichier.html.

Les spécificateurs de format %V et %A de la directive LogFormat s'avèrent très utiles lorsqu'ils sont utilisés en conjonction avec ce module.

Directive VirtualDocumentRoot

Description: | Permet une configuration dynamique de la racine des documents d'un serveur virtuel donné
Syntaxe: | VirtualDocumentRoot répertoire-interpolé|none
Défaut: | VirtualDocumentRoot none
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_vhost_alias

La directive VirtualDocumentRoot vous permet de spécifier où le serveur HTTP Apache pourra trouver vos documents en se basant sur le nom du serveur. Le résultat de l'expansion du répertoire-interpolé est utilisé comme racine de l'arborescence des documents d'une manière similaire à l'argument de la directive DocumentRoot. Si répertoire-interpolé a pour valeur none, la directive VirtualDocumentRoot est désactivée. Cette directive ne peut pas être utilisée dans le même contexte que la directive VirtualDocumentRootIP.

Note

La directive VirtualDocumentRoot l'emporte sur toute directive DocumentRoot définie dans le même contexte ou dans des contextes enfants. Le fait de définir une directive VirtualDocumentRoot dans le contexte du serveur principal va effectivement l'emporter sur toute directive DocumentRoot définie dans un serveur virtuel quelconque, si vous n'avez pas défini VirtualDocumentRoot à None dans ce serveur virtuel.

Directive VirtualDocumentRootIP

Description: | Configuration dynamique de la racine des documents pour un serveur virtuel donné
Syntaxe: | VirtualDocumentRootIP répertoire-interpolé|none
Défaut: | VirtualDocumentRootIP none
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_vhost_alias

La directive VirtualDocumentRootIP est identique à la directive VirtualDocumentRoot à l'exception près qu'elle utilise l'adresse IP du serveur virtuel pour l'interpolation du répertoire à la place du nom du serveur.

Directive VirtualScriptAlias

Description: | Configuration dynamique du répertoire des scripts CGI pour un serveur virtuel donné
Syntaxe: | VirtualScriptAlias répertoire-interpolé|none
Défaut: | VirtualScriptAlias none
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_vhost_alias

La directive VirtualScriptAlias vous permet de spécifier où Apache httpd pourra trouver les scripts CGI selon une méthode similaire à celle qu'utilise la directive VirtualDocumentRoot pour les autres documents. Elle recherche des requêtes dont l'URI commence par /cgi-bin/, comme le ferait la directive ScriptAlias.

Directive VirtualScriptAliasIP

Description: | Configuration dynamique du répertoire des scripts CGI pour un serveur virtuel donné
Syntaxe: | VirtualScriptAliasIP répertoire-interpolé|none
Défaut: | VirtualScriptAliasIP none
Contexte: | configuration du serveur, serveur virtuel
Statut: | Extension
Module: | mod_vhost_alias

La directive VirtualScriptAliasIP est identique à la directive VirtualScriptAlias à l'exception près qu'elle utilise l'adresse IP du serveur virtuel pour l'interpolation du répertoire à la place du nom du serveur.


mod_watchdog - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_watchdog

Description: | provides infrastructure for other modules to periodically run tasks
Status: | Base
Module Identifier: | watchdog_module
Source File: | mod_watchdog.c
Compatibility: | Available in Apache 2.3 and later

Summary

mod_watchdog defines programmatic hooks for other modules to periodically run tasks. These modules can register handlers for mod_watchdog hooks. Currently, the following modules in the Apache distribution use this functionality:

  • mod_heartbeat
  • mod_heartmonitor
To allow a module to use mod_watchdog functionality, mod_watchdog itself must be statically linked to the server core or, if a dynamic module, be loaded before the calling module.

WatchdogInterval Directive

Description: | Watchdog interval in seconds
Syntax: | WatchdogInterval number-of-seconds
Default: | WatchdogInterval 1
Context: | server config
Status: | Base
Module: | mod_watchdog

Sets the interval at which the watchdog_step hook runs. Default is to run every second.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_xml2enc - Serveur Apache HTTP Version 2.4

Module Apache mod_xml2enc

Description: | Support avancé de l'internationalisation et des jeux de caractères pour les modules de filtrage basés sur libxml2
Statut: | Base
Identificateur de Module: | xml2enc_module
Fichier Source: | mod_xml2enc.c
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.2.x

Sommaire

Ce module fournit un support avancé de l'internationalisation pour les modules de filtrage supportant les balises (markup-aware) comme mod_proxy_html. Il est capable de détecter automatiquement l'encodage des données en entrée et de s'assurer qu'elle sont traitées correctement par l'interpréteur libxml2, y compris la conversion en Unicode (UTF-8) si nécessaire. Il peut aussi convertir les données dans l'encodage de votre choix après le traitement des balises, et s'assurera que le jeu de caractères approprié sera défini dans l'en-tête HTTP Content-Type.

Utilisation

Il existe deux scénarios d'utilisation : le cas des modules programmés pour travailler avec mod_xml2enc ; et les autres :

Modules de filtrages programmés pour mod_xml2enc

Les modules comme mod_proxy_html versions 3.1 et supérieures utilisent la fonction optionnelle xml2enc_charset pour déterminer la valeur de l'argument "jeu de caractères" à transmettre à l'interpréteur libxml2, et disposent de la fonction optionnelle xml2enc_filter pour effectuer un encodage ultérieur éventuel. L'utilisation de mod_xml2enc avec un module préprogrammé à cet effet ne nécessite aucune configuration : ce dernier configurera mod_xml2enc pour vous (sachant que vous pouvez tout de même le personnaliser via les directives de configuration ci-dessous).

Modules de filtrages non programmés pour mod_xml2enc

Pour utiliser mod_xml2enc avec un module basé sur libxml2 qui n'a pas été explicitement programmé pour mod_xml2enc, vous devrez configurer la chaîne de filtrage vous-même. Ainsi, pour utiliser mod_xml2enc avec un filtre foo fourni par un module mod_foo et pour améliorer le support i18n de ce dernier avec HTML et XML, vous pouvez utiliser les directives suivantes :

    FilterProvider iconv    xml2enc Content-Type $text/html
    FilterProvider iconv    xml2enc Content-Type $xml
    FilterProvider markup   foo Content-Type $text/html
    FilterProvider markup   foo Content-Type $xml
    FilterChain     iconv markup

mod_foo supportera alors tout jeu de caractère supporté soit par libxml2, soit par apr_xlate/iconv, soit par les deux.

API de programmation

Les programmeurs de modules de filtrage basés sur libxml2 sont encouragés à les préprogrammer pour mod_xml2enc, afin de fournir un support i18n solide aux utilisateurs sans avoir à réinventer la roue. L'API de programmation est décrite dans mod_xml2enc.h, et mod_proxy_html est un exemple de son utilisation.

Détection et encodage

A la différence de mod_charset_lite, mod_xml2enc est conçu pour travailler avec des données dont l'encodage ne peut pas être connu, et donc configuré, à l'avance. Il utilise donc les techniques de 'reniflage' suivantes pour détecter le type d'encodage des données HTTP :

  1. Si l'en-tête HTTP Content-Type contient un paramètre charset, c'est ce dernier qui sera utilisé.
  2. Si les données commancent par une balise XML concernant l'ordre des octets (BOM) ou par une déclaration d'encodage XML, c'est celle-ci qui sera utilisée.
  3. Si un type d'encodage est déclaré dans un élément HTML <META>, c'est ce dernier qui sera utilisé.
  4. Si aucun des éléments précédents n'est trouvé, c'est la valeur par défaut définie par la directive xml2EncDefault qui sera utilisée.

Les conditions sont testées dans cet ordre . Dès qu'une règle s'applique, elle est utilisée et la détection est terminée.

Codage en sortie

libxml2 utilise toujours UTF-8 (Unicode) en interne, et les modules de filtrage basés sur libxml2 utiliseront cet encodage en sortie par défaut. mod_xml2enc peut modifier l'encodage en sortie via l'API, mais il n'y a actuellement aucun moyen de le configurer directement.

La modification de l'encodage en sortie ne devrait (du moins en théorie) jamais être nécessaire, et est même déconseillée à cause de la charge de traitement supplémentaire imposée au serveur par une conversion non nécessaire.

Codages non supportés

Si vous travaillez avec des encodages non supportés par aucune des méthodes de conversion disponibles sur votre plateforme, vous pouvez tout de même leur associer un alias vers un code supporté via la directive xml2EncAlias.

Directive xml2EncAlias

Description: | Définit des alias pour les valeurs d'encodage
Syntaxe: | xml2EncAlias jeu-de-caractères alias [alias ...]
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_xml2enc

Cette directive de niveau serveur permet de définir un ou plusieurs alias pour un encodage. Elle permet au support d'encodage de libxml2 de traiter en interne des encodages non reconnus par libxml2 en utilisant la table de conversion pour un encodage reconnu. Elle permet d'atteindre deux objectifs : supporter des jeux (ou noms) de caractères non reconnus par libxml2 ou iconv, et éviter une conversion pour un encodage lorsque cela n'est pas nécessaire.

Directive xml2EncDefault

Description: | Définit un encodage par défaut à utiliser lorsqu'aucune information ne peut être automatiquement détectée
Syntaxe: | xml2EncDefault nom
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Base
Module: | mod_xml2enc
Compatibilité: | Disponible depuis la version 2.4.0 du serveur HTTP Apache ; disponible depuis un module tiers dans les versions antérieures.

Si vous traitez des données dont l'encodage est connu, mais ne contenant aucune information à propos de ce dernier, vous pouvez définir une valeur par défaut afin d'aider mod_xml2enc à traiter correctement les données. Par exemple, pour définir la valeur par défaut Latin1 (iso-8859-1 specifiée dans HTTP/1.0), utilisez :

xml2EncDefault iso-8859-1

Directive xml2StartParse

Description: | Indique à l'interpréteur à partir de quelle balise il doit commencer son traitement.
Syntaxe: | xml2StartParse élément [élément ...]
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Base
Module: | mod_xml2enc

Cette directive permet de spécifier à partir de quelle balise, parmi les éléments spécifiés, l'interpréteur de balise doit commencer son traitement. Ccei permet de contourner le problème des serveurs d'arrière-plan qui insèrent des éléments non conformes en début de données, ce qui a pour effet de perturber l'interpréteur (voir un exemple ici).

Elle ne doit être utilisée ni pour les documents XML, ni pour les documents HTML correctement formatés.


Developer Documentation for the Apache HTTP Server 2.4 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Developer Documentation for the Apache HTTP Server 2.4

Warning

Many of the documents listed here are in need of update. They are in different stages of progress. Please be patient and follow this link to propose a fix or point out any error/discrepancy.

2.4 development documents

  • Developing modules for the Apache HTTP Server 2.4
  • Hook Functions in 2.4
  • Request Processing in 2.4
  • How filters work in 2.4
  • Guidelines for output filters in 2.4
  • Documenting code in 2.4
  • Thread Safety Issues in 2.4

Upgrading to 2.4

  • API changes in 2.3/2.4
  • Converting Modules from 1.3 to 2.x

External Resources

  • Autogenerated Apache HTTP Server (trunk) code documentation (the link is built by this job).
  • Developer articles at apachetutor include:
    • Request Processing
    • Configuration for Modules
    • Resource Management
    • Connection Pooling
    • Introduction to Buckets and Brigades

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache 1.3 API notes - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Apache 1.3 API notes

Warning

This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

These are some notes on the Apache API and the data structures you have to deal with, etc. They are not yet nearly complete, but hopefully, they will help you get your bearings. Keep in mind that the API is still subject to change as we gain experience with it. (See the TODO file for what might be coming). However, it will be easy to adapt modules to any changes that are made. (We have more modules to adapt than you do).

A few notes on general pedagogical style here. In the interest of conciseness, all structure declarations here are incomplete -- the real ones have more slots that I'm not telling you about. For the most part, these are reserved to one component of the server core or another, and should be altered by modules with caution. However, in some cases, they really are things I just haven't gotten around to yet. Welcome to the bleeding edge.

Finally, here's an outline, to give you some bare idea of what's coming up, and in what order:

  • Basic concepts.
    • Handlers, Modules, and Requests
    • A brief tour of a module
  • How handlers work
    • A brief tour of the request_rec
    • Where request_rec structures come from
    • Handling requests, declining, and returning error codes
    • Special considerations for response handlers
    • Special considerations for authentication handlers
    • Special considerations for logging handlers
  • Resource allocation and resource pools
  • Configuration, commands and the like
    • Per-directory configuration structures
    • Command handling
    • Side notes --- per-server configuration, virtual servers, etc.

Basic concepts

We begin with an overview of the basic concepts behind the API, and how they are manifested in the code.

Handlers, Modules, and Requests

Apache breaks down request handling into a series of steps, more or less the same way the Netscape server API does (although this API has a few more stages than NetSite does, as hooks for stuff I thought might be useful in the future). These are:

  • URI -> Filename translation
  • Auth ID checking [is the user who they say they are?]
  • Auth access checking [is the user authorized here?]
  • Access checking other than auth
  • Determining MIME type of the object requested
  • `Fixups' -- there aren't any of these yet, but the phase is intended as a hook for possible extensions like SetEnv, which don't really fit well elsewhere.
  • Actually sending a response back to the client.
  • Logging the request

These phases are handled by looking at each of a succession of modules, looking to see if each of them has a handler for the phase, and attempting invoking it if so. The handler can typically do one of three things:

  • Handle the request, and indicate that it has done so by returning the magic constant OK.
  • Decline to handle the request, by returning the magic integer constant DECLINED. In this case, the server behaves in all respects as if the handler simply hadn't been there.
  • Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case.

Most phases are terminated by the first module that handles them; however, for logging, `fixups', and non-access authentication checking, all handlers always run (barring an error). Also, the response phase is unique in that modules may declare multiple handlers for it, via a dispatch table keyed on the MIME type of the requested object. Modules may declare a response-phase handler which can handle any request, by giving it the key */* (i.e., a wildcard MIME type specification). However, wildcard handlers are only invoked if the server has already tried and failed to find a more specific response handler for the MIME type of the requested object (either none existed, or they all declined).

The handlers themselves are functions of one argument (a request_rec structure. vide infra), which returns an integer, as above.

A brief tour of a module

At this point, we need to explain the structure of a module. Our candidate will be one of the messier ones, the CGI module -- this handles both CGI scripts and the ScriptAlias config file command. It's actually a great deal more complicated than most modules, but if we're going to have only one example, it might as well be the one with its fingers in every place.

Let's begin with handlers. In order to handle the CGI scripts, the module declares a response handler for them. Because of ScriptAlias, it also has handlers for the name translation phase (to recognize ScriptAliased URIs), the type-checking phase (any ScriptAliased request is typed as a CGI script).

The module needs to maintain some per (virtual) server information, namely, the ScriptAliases in effect; the module structure therefore contains pointers to a functions which builds these structures, and to another which combines two of them (in case the main server and a virtual server both have ScriptAliases declared).

Finally, this module contains code to handle the ScriptAlias command itself. This particular module only declares one command, but there could be more, so modules have command tables which declare their commands, and describe where they are permitted, and how they are to be invoked.

A final note on the declared types of the arguments of some of these commands: a pool is a pointer to a resource pool structure; these are used by the server to keep track of the memory which has been allocated, files opened, etc., either to service a particular request, or to handle the process of configuring itself. That way, when the request is over (or, for the configuration pool, when the server is restarting), the memory can be freed, and the files closed, en masse, without anyone having to write explicit code to track them all down and dispose of them. Also, a cmd_parms structure contains various information about the config file being read, and other status information, which is sometimes of use to the function which processes a config-file command (such as ScriptAlias). With no further ado, the module itself:

        /* Declarations of handlers. */

int translate_scriptalias (request_rec *);
int type_scriptalias (request_rec *);
int cgi_handler (request_rec *);

/* Subsidiary dispatch table for response-phase
* handlers, by MIME type */

handler_rec cgi_handlers[] = {
{ "application/x-httpd-cgi", cgi_handler },
{ NULL }
};

/* Declarations of routines to manipulate the
* module's configuration info.  Note that these are
* returned, and passed in, as void *'s; the server
* core keeps track of them, but it doesn't, and can't,
* know their internal structure.
*/

void *make_cgi_server_config (pool *);
void *merge_cgi_server_config (pool *, void *, void *);

/* Declarations of routines to handle config-file commands */

extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
                                  char *real);

command_rec cgi_cmds[] = {
{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
"a fakename and a realname"},
{ NULL }
};

module cgi_module = {

  STANDARD_MODULE_STUFF,
  NULL,                     /* initializer */
  NULL,                     /* dir config creator */
  NULL,                     /* dir merger */
  make_cgi_server_config,   /* server config */
  merge_cgi_server_config,  /* merge server config */
  cgi_cmds,                 /* command table */
  cgi_handlers,             /* handlers */
  translate_scriptalias,    /* filename translation */
  NULL,                     /* check_user_id */
  NULL,                     /* check auth */
  NULL,                     /* check access */
  type_scriptalias,         /* type_checker */
  NULL,                     /* fixups */
  NULL,                     /* logger */
  NULL                      /* header parser */
};

How handlers work

The sole argument to handlers is a request_rec structure. This structure describes a particular request which has been made to the server, on behalf of a client. In most cases, each connection to the client generates only one request_rec structure.

A brief tour of the request_rec

The request_rec contains pointers to a resource pool which will be cleared when the server is finished handling the request; to structures containing per-server and per-connection information, and most importantly, information on the request itself.

The most important such information is a small set of character strings describing attributes of the object being requested, including its URI, filename, content-type and content-encoding (these being filled in by the translation and type-check handlers which handle the request, respectively).

Other commonly used data items are tables giving the MIME headers on the client's original request, MIME headers to be sent back with the response (which modules can add to at will), and environment variables for any subprocesses which are spawned off in the course of servicing the request. These tables are manipulated using the ap_table_get and ap_table_set routines.

Note that the Content-type header value cannot be set by module content-handlers using the ap_table_*() routines. Rather, it is set by pointing the content_type field in the request_rec structure to an appropriate string. e.g.,

r->content_type = "text/html";

Finally, there are pointers to two data structures which, in turn, point to per-module configuration structures. Specifically, these hold pointers to the data structures which the module has built to describe the way it has been configured to operate in a given directory (via .htaccess files or <Directory> sections), for private data it has built in the course of servicing the request (so modules' handlers for one phase can pass `notes' to their handlers for other phases). There is another such configuration vector in the server_rec data structure pointed to by the request_rec, which contains per (virtual) server configuration data.

Here is an abridged declaration, giving the fields most commonly used:

struct request_rec {

pool *pool;
conn_rec *connection;
server_rec *server;

/* What object is being requested */

char *uri;
char *filename;
char *path_info;

char *args;           /* QUERY_ARGS, if any */
struct stat finfo;    /* Set by server core;
                       * st_mode set to zero if no such file */

char *content_type;
char *content_encoding;

/* MIME header environments, in and out. Also,
 * an array containing environment variables to
 * be passed to subprocesses, so people can write
 * modules to add to that environment.
 *
 * The difference between headers_out and
 * err_headers_out is that the latter are printed
 * even on error, and persist across internal
 * redirects (so the headers printed for
 * ErrorDocument handlers will have them).
 */

table *headers_in;
table *headers_out;
table *err_headers_out;
table *subprocess_env;

/* Info about the request itself... */

int header_only;     /* HEAD request, as opposed to GET */
char *protocol;      /* Protocol, as given to us, or HTTP/0.9 */
char *method;        /* GET, HEAD, POST, etc. */
int method_number;   /* M_GET, M_POST, etc. */

/* Info for logging */

char *the_request;
int bytes_sent;

/* A flag which modules can set, to indicate that
 * the data being returned is volatile, and clients
 * should be told not to cache it.
 */

int no_cache;

/* Various other config info which may change
 * with .htaccess files
 * These are config vectors, with one void*
 * pointer for each module (the thing pointed
 * to being the module's business).
 */

void *per_dir_config;   /* Options set in config files, etc. */
void *request_config;   /* Notes on *this* request */

};

Where request_rec structures come from

Most request_rec structures are built by reading an HTTP request from a client, and filling in the fields. However, there are a few exceptions:

  • If the request is to an imagemap, a type map (i.e., a *.var file), or a CGI script which returned a local `Location:', then the resource which the user requested is going to be ultimately located by some URI other than what the client originally supplied. In this case, the server does an internal redirect, constructing a new request_rec for the new URI, and processing it almost exactly as if the client had requested the new URI directly.
  • If some handler signaled an error, and an ErrorDocument is in scope, the same internal redirect machinery comes into play.

  • Finally, a handler occasionally needs to investigate `what would happen if' some other request were run. For instance, the directory indexing module needs to know what MIME type would be assigned to a request for each directory entry, in order to figure out what icon to use.

    Such handlers can construct a sub-request, using the functions ap_sub_req_lookup_file, ap_sub_req_lookup_uri, and ap_sub_req_method_uri; these construct a new request_rec structure and processes it as you would expect, up to but not including the point of actually sending a response. (These functions skip over the access checks if the sub-request is for a file in the same directory as the original request).

    (Server-side includes work by building sub-requests and then actually invoking the response handler for them, via the function ap_run_sub_req).

Handling requests, declining, and returning error codes

As discussed above, each handler, when invoked to handle a particular request_rec, has to return an int to indicate what happened. That can either be

  • OK -- the request was handled successfully. This may or may not terminate the phase.
  • DECLINED -- no erroneous condition exists, but the module declines to handle the phase; the server tries to find another.
  • an HTTP error code, which aborts handling of the request.

Note that if the error code returned is REDIRECT, then the module should put a Location in the request's headers_out, to indicate where the client should be redirected to.

Special considerations for response handlers

Handlers for most phases do their work by simply setting a few fields in the request_rec structure (or, in the case of access checkers, simply by returning the correct error code). However, response handlers have to actually send a request back to the client.

They should begin by sending an HTTP response header, using the function ap_send_http_header. (You don't have to do anything special to skip sending the header for HTTP/0.9 requests; the function figures out on its own that it shouldn't do anything). If the request is marked header_only, that's all they should do; they should return after that, without attempting any further output.

Otherwise, they should produce a request body which responds to the client as appropriate. The primitives for this are ap_rputc and ap_rprintf, for internally generated output, and ap_send_fd, to copy the contents of some FILE * straight to the client.

At this point, you should more or less understand the following piece of code, which is the handler which handles GET requests which have no more specific handler; it also shows how conditional GETs can be handled, if it's desirable to do so in a particular response handler -- ap_set_last_modified checks against the If-modified-since value supplied by the client, if any, and returns an appropriate code (which will, if nonzero, be USE_LOCAL_COPY). No similar considerations apply for ap_set_content_length, but it returns an error code for symmetry.

        int default_handler (request_rec *r)
{
int errstatus;
FILE *f;

if (r->method_number != M_GET) return DECLINED;
if (r->finfo.st_mode == 0) return NOT_FOUND;

if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
||
             (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
return errstatus;

f = fopen (r->filename, "r");

if (f == NULL) {
log_reason("file permissions deny server access", r->filename, r);
return FORBIDDEN;
}

register_timeout ("send", r);
ap_send_http_header (r);

if (!r->header_only) send_fd (f, r);
ap_pfclose (r->pool, f);
return OK;
}

Finally, if all of this is too much of a challenge, there are a few ways out of it. First off, as shown above, a response handler which has not yet produced any output can simply return an error code, in which case the server will automatically produce an error response. Secondly, it can punt to some other handler by invoking ap_internal_redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has internally redirected should always return OK.

(Invoking ap_internal_redirect from handlers which are not response handlers will lead to serious confusion).

Special considerations for authentication handlers

Stuff that should be discussed here in detail:

  • Authentication-phase handlers not invoked unless auth is configured for the directory.
  • Common auth configuration stored in the core per-dir configuration; it has accessors ap_auth_type, ap_auth_name, and ap_requires.
  • Common routines, to handle the protocol end of things, at least for HTTP basic authentication (ap_get_basic_auth_pw, which sets the connection->user structure field automatically, and ap_note_basic_auth_failure, which arranges for the proper WWW-Authenticate: header to be sent back).

Special considerations for logging handlers

When a request has internally redirected, there is the question of what to log. Apache handles this by bundling the entire chain of redirects into a list of request_rec structures which are threaded through the r->prev and r->next pointers. The request_rec which is passed to the logging handlers in such cases is the one which was originally built for the initial request from the client; note that the bytes_sent field will only be correct in the last request in the chain (the one for which a response was actually sent).

Resource allocation and resource pools

One of the problems of writing and designing a server-pool server is that of preventing leakage, that is, allocating resources (memory, open files, etc.), without subsequently releasing them. The resource pool machinery is designed to make it easy to prevent this from happening, by allowing resource to be allocated in such a way that they are automatically released when the server is done with them.

The way this works is as follows: the memory which is allocated, file opened, etc., to deal with a particular request are tied to a resource pool which is allocated for the request. The pool is a data structure which itself tracks the resources in question.

When the request has been processed, the pool is cleared. At that point, all the memory associated with it is released for reuse, all files associated with it are closed, and any other clean-up functions which are associated with the pool are run. When this is over, we can be confident that all the resource tied to the pool have been released, and that none of them have leaked.

Server restarts, and allocation of memory and resources for per-server configuration, are handled in a similar way. There is a configuration pool, which keeps track of resources which were allocated while reading the server configuration files, and handling the commands therein (for instance, the memory that was allocated for per-server module configuration, log files and other files that were opened, and so forth). When the server restarts, and has to reread the configuration files, the configuration pool is cleared, and so the memory and file descriptors which were taken up by reading them the last time are made available for reuse.

It should be noted that use of the pool machinery isn't generally obligatory, except for situations like logging handlers, where you really need to register cleanups to make sure that the log file gets closed when the server restarts (this is most easily done by using the function ap_pfopen, which also arranges for the underlying file descriptor to be closed before any child processes, such as for CGI scripts, are execed), or in case you are using the timeout machinery (which isn't yet even documented here). However, there are two benefits to using it: resources allocated to a pool never leak (even if you allocate a scratch string, and just forget about it); also, for memory allocation, ap_palloc is generally faster than malloc.

We begin here by describing how memory is allocated to pools, and then discuss how other resources are tracked by the resource pool machinery.

Allocation of memory in pools

Memory is allocated to pools by calling the function ap_palloc, which takes two arguments, one being a pointer to a resource pool structure, and the other being the amount of memory to allocate (in chars). Within handlers for handling requests, the most common way of getting a resource pool structure is by looking at the pool slot of the relevant request_rec; hence the repeated appearance of the following idiom in module code:

int my_handler(request_rec *r)
{
struct my_structure *foo;
...

foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));
 }

Note that there is no ap_pfree -- ap_palloced memory is freed only when the associated resource pool is cleared. This means that ap_palloc does not have to do as much accounting as malloc(); all it does in the typical case is to round up the size, bump a pointer, and do a range check.

(It also raises the possibility that heavy use of ap_palloc could cause a server process to grow excessively large. There are two ways to deal with this, which are dealt with below; briefly, you can use malloc, and try to be sure that all of the memory gets explicitly freed, or you can allocate a sub-pool of the main pool, allocate your memory in the sub-pool, and clear it out periodically. The latter technique is discussed in the section on sub-pools below, and is used in the directory-indexing code, in order to avoid excessive storage allocation when listing directories with thousands of files).

Allocating initialized memory

There are functions which allocate initialized memory, and are frequently useful. The function ap_pcalloc has the same interface as ap_palloc, but clears out the memory it allocates before it returns it. The function ap_pstrdup takes a resource pool and a char * as arguments, and allocates memory for a copy of the string the pointer points to, returning a pointer to the copy. Finally ap_pstrcat is a varargs-style function, which takes a pointer to a resource pool, and at least two char * arguments, the last of which must be NULL. It allocates enough memory to fit copies of each of the strings, as a unit; for instance:

ap_pstrcat (r->pool, "foo", "/", "bar", NULL);

returns a pointer to 8 bytes worth of memory, initialized to "foo/bar".

Commonly-used pools in the Apache Web server

A pool is really defined by its lifetime more than anything else. There are some static pools in http_main which are passed to various non-http_main functions as arguments at opportune times. Here they are:

permanent_pool
never passed to anything else, this is the ancestor of all pools
pconf
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the server is terminated or restarts; passed to all config-time routines, either via cmd->pool, or as the "pool *p" argument on those which don't take pools
  • passed to the module init() functions
ptemp
  • sorry I lie, this pool isn't called this currently in 1.3, I renamed it this in my pthreads development. I'm referring to the use of ptrans in the parent... contrast this with the later definition of ptrans in the child.
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the end of config parsing; passed to config-time routines via cmd->temp_pool. Somewhat of a "bastard child" because it isn't available everywhere. Used for temporary scratch space which may be needed by some config routines but which is deleted at the end of config.
pchild
  • subpool of permanent_pool
  • created when a child is spawned (or a thread is created); lives until that child (thread) is destroyed
  • passed to the module child_init functions
  • destruction happens right after the child_exit functions are called... (which may explain why I think child_exit is redundant and unneeded)
ptrans
  • should be a subpool of pchild, but currently is a subpool of permanent_pool, see above
  • cleared by the child before going into the accept() loop to receive a connection
  • used as connection->pool
r->pool
  • for the main request this is a subpool of connection->pool; for subrequests it is a subpool of the parent request's pool.
  • exists until the end of the request (i.e., ap_destroy_sub_req, or in child_main after process_request has finished)
  • note that r itself is allocated from r->pool; i.e., r->pool is first created and then r is the first thing palloc()d from it

For almost everything folks do, r->pool is the pool to use. But you can see how other lifetimes, such as pchild, are useful to some modules... such as modules that need to open a database connection once per child, and wish to clean it up when the child dies.

You can also see how some bugs have manifested themself, such as setting connection->user to a value from r->pool -- in this case connection exists for the lifetime of ptrans, which is longer than r->pool (especially if r->pool is a subrequest!). So the correct thing to do is to allocate from connection->pool.

And there was another interesting bug in mod_include / mod_cgi. You'll see in those that they do this test to decide if they should use r->pool or r->main->pool. In this case the resource that they are registering for cleanup is a child process. If it were registered in r->pool, then the code would wait() for the child when the subrequest finishes. With mod_include this could be any old #include, and the delay can be up to 3 seconds... and happened quite frequently. Instead the subprocess is registered in r->main->pool which causes it to be cleaned up when the entire request is done -- i.e., after the output has been sent to the client and logging has happened.

Tracking open files, etc.

As indicated above, resource pools are also used to track other sorts of resources besides memory. The most common are open files. The routine which is typically used for this is ap_pfopen, which takes a resource pool and two strings as arguments; the strings are the same as the typical arguments to fopen, e.g.,

...
FILE *f = ap_pfopen (r->pool, r->filename, "r");

if (f == NULL) { ... } else { ... }

There is also a ap_popenf routine, which parallels the lower-level open system call. Both of these routines arrange for the file to be closed when the resource pool in question is cleared.

Unlike the case for memory, there are functions to close files allocated with ap_pfopen, and ap_popenf, namely ap_pfclose and ap_pclosef. (This is because, on many systems, the number of files which a single process can have open is quite limited). It is important to use these functions to close files allocated with ap_pfopen and ap_popenf, since to do otherwise could cause fatal errors on systems such as Linux, which react badly if the same FILE* is closed more than once.

(Using the close functions is not mandatory, since the file will eventually be closed regardless, but you should consider it in cases where your module is opening, or could open, a lot of files).

Other sorts of resources -- cleanup functions

More text goes here. Describe the cleanup primitives in terms of which the file stuff is implemented; also, spawn_process.

Pool cleanups live until clear_pool() is called: clear_pool(a) recursively calls destroy_pool() on all subpools of a; then calls all the cleanups for a; then releases all the memory for a. destroy_pool(a) calls clear_pool(a) and then releases the pool structure itself. i.e., clear_pool(a) doesn't delete a, it just frees up all the resources and you can start using it again immediately.

Fine control -- creating and dealing with sub-pools, with a note on sub-requests

On rare occasions, too-free use of ap_palloc() and the associated primitives may result in undesirably profligate resource allocation. You can deal with such a case by creating a sub-pool, allocating within the sub-pool rather than the main pool, and clearing or destroying the sub-pool, which releases the resources which were associated with it. (This really is a rare situation; the only case in which it comes up in the standard module set is in case of listing directories, and then only with very large directories. Unnecessary use of the primitives discussed here can hair up your code quite a bit, with very little gain).

The primitive for creating a sub-pool is ap_make_sub_pool, which takes another pool (the parent pool) as an argument. When the main pool is cleared, the sub-pool will be destroyed. The sub-pool may also be cleared or destroyed at any time, by calling the functions ap_clear_pool and ap_destroy_pool, respectively. (The difference is that ap_clear_pool frees resources associated with the pool, while ap_destroy_pool also deallocates the pool itself. In the former case, you can allocate new resources within the pool, and clear it again, and so forth; in the latter case, it is simply gone).

One final note -- sub-requests have their own resource pools, which are sub-pools of the resource pool for the main request. The polite way to reclaim the resources associated with a sub request which you have allocated (using the ap_sub_req_... functions) is ap_destroy_sub_req, which frees the resource pool. Before calling this function, be sure to copy anything that you care about which might be allocated in the sub-request's resource pool into someplace a little less volatile (for instance, the filename in its request_rec structure).

(Again, under most circumstances, you shouldn't feel obliged to call this function; only 2K of memory or so are allocated for a typical sub request, and it will be freed anyway when the main request pool is cleared. It is only when you are allocating many, many sub-requests for a single main request that you should seriously consider the ap_destroy_... functions).

Configuration, commands and the like

One of the design goals for this server was to maintain external compatibility with the NCSA 1.3 server --- that is, to read the same configuration files, to process all the directives therein correctly, and in general to be a drop-in replacement for NCSA. On the other hand, another design goal was to move as much of the server's functionality into modules which have as little as possible to do with the monolithic server core. The only way to reconcile these goals is to move the handling of most commands from the central server into the modules.

However, just giving the modules command tables is not enough to divorce them completely from the server core. The server has to remember the commands in order to act on them later. That involves maintaining data which is private to the modules, and which can be either per-server, or per-directory. Most things are per-directory, including in particular access control and authorization information, but also information on how to determine file types from suffixes, which can be modified by AddType and ForceType directives, and so forth. In general, the governing philosophy is that anything which can be made configurable by directory should be; per-server information is generally used in the standard set of modules for information like Aliases and Redirects which come into play before the request is tied to a particular place in the underlying file system.

Another requirement for emulating the NCSA server is being able to handle the per-directory configuration files, generally called .htaccess files, though even in the NCSA server they can contain directives which have nothing at all to do with access control. Accordingly, after URI -> filename translation, but before performing any other phase, the server walks down the directory hierarchy of the underlying filesystem, following the translated pathname, to read any .htaccess files which might be present. The information which is read in then has to be merged with the applicable information from the server's own config files (either from the <Directory> sections in access.conf, or from defaults in srm.conf, which actually behaves for most purposes almost exactly like <Directory />).

Finally, after having served a request which involved reading .htaccess files, we need to discard the storage allocated for handling them. That is solved the same way it is solved wherever else similar problems come up, by tying those structures to the per-transaction resource pool.

Per-directory configuration structures

Let's look out how all of this plays out in mod_mime.c, which defines the file typing handler which emulates the NCSA server's behavior of determining file types from suffixes. What we'll be looking at, here, is the code which implements the AddType and AddEncoding commands. These commands can appear in .htaccess files, so they must be handled in the module's private per-directory data, which in fact, consists of two separate tables for MIME types and encoding information, and is declared as follows:

typedef struct {
    table *forced_types;      /* Additional AddTyped stuff */
    table *encoding_types;    /* Added with AddEncoding... */
} mime_dir_config;

When the server is reading a configuration file, or <Directory> section, which includes one of the MIME module's commands, it needs to create a mime_dir_config structure, so those commands have something to act on. It does this by invoking the function it finds in the module's `create per-dir config slot', with two arguments: the name of the directory to which this configuration information applies (or NULL for srm.conf), and a pointer to a resource pool in which the allocation should happen.

(If we are reading a .htaccess file, that resource pool is the per-request resource pool for the request; otherwise it is a resource pool which is used for configuration data, and cleared on restarts. Either way, it is important for the structure being created to vanish when the pool is cleared, by registering a cleanup on the pool if necessary).

For the MIME module, the per-dir config creation function just ap_pallocs the structure above, and a creates a couple of tables to fill it. That looks like this:

void *create_mime_dir_config (pool *p, char *dummy)
{
mime_dir_config *new =
(mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_make_table (p, 4);
new->encoding_types = ap_make_table (p, 4);

return new;
 }

Now, suppose we've just read in a .htaccess file. We already have the per-directory configuration structure for the next directory up in the hierarchy. If the .htaccess file we just read in didn't have any AddType or AddEncoding commands, its per-directory config structure for the MIME module is still valid, and we can just use it. Otherwise, we need to merge the two structures somehow.

To do that, the server invokes the module's per-directory config merge function, if one is present. That function takes three arguments: the two structures being merged, and a resource pool in which to allocate the result. For the MIME module, all that needs to be done is overlay the tables from the new per-directory config structure with those from the parent:

void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
{
mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
mime_dir_config *subdir = (mime_dir_config *)subdirv;
mime_dir_config *new =
(mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_overlay_tables (p, subdir->forced_types,
parent_dir->forced_types);
 new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,
parent_dir->encoding_types);
return new;
 }

As a note -- if there is no per-directory merge function present, the server will just use the subdirectory's configuration info, and ignore the parent's. For some modules, that works just fine (e.g., for the includes module, whose per-directory configuration information consists solely of the state of the XBITHACK), and for those modules, you can just not declare one, and leave the corresponding structure slot in the module itself NULL.

Command handling

Now that we have these structures, we need to be able to figure out how to fill them. That involves processing the actual AddType and AddEncoding commands. To find commands, the server looks in the module's command table. That table contains information on how many arguments the commands take, and in what formats, where it is permitted, and so forth. That information is sufficient to allow the server to invoke most command-handling functions with pre-parsed arguments. Without further ado, let's look at the AddType command handler, which looks like this (the AddEncoding command looks basically the same, and won't be shown here):

char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
{
if (*ext == '.') ++ext;
ap_table_set (m->forced_types, ext, ct);
return NULL;
 }

This command handler is unusually simple. As you can see, it takes four arguments, two of which are pre-parsed arguments, the third being the per-directory configuration structure for the module in question, and the fourth being a pointer to a cmd_parms structure. That structure contains a bunch of arguments which are frequently of use to some, but not all, commands, including a resource pool (from which memory can be allocated, and to which cleanups should be tied), and the (virtual) server being configured, from which the module's per-server configuration data can be obtained if required.

Another way in which this particular command handler is unusually simple is that there are no error conditions which it can encounter. If there were, it could return an error message instead of NULL; this causes an error to be printed out on the server's stderr, followed by a quick exit, if it is in the main config files; for a .htaccess file, the syntax error is logged in the server error log (along with an indication of where it came from), and the request is bounced with a server error response (HTTP error status, code 500).

The MIME module's command table has entries for these commands, which look like this:

command_rec mime_cmds[] = {
{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
"a mime type followed by a file extension" },
 { "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
"an encoding (e.g., gzip), followed by a file extension" },
 { NULL }
 };

The entries in these tables are:

  • The name of the command
  • The function which handles it
  • a (void *) pointer, which is passed in the cmd_parms structure to the command handler --- this is useful in case many similar commands are handled by the same function.
  • A bit mask indicating where the command may appear. There are mask bits corresponding to each AllowOverride option, and an additional mask bit, RSRC_CONF, indicating that the command may appear in the server's own config files, but not in any .htaccess file.
  • A flag indicating how many arguments the command handler wants pre-parsed, and how they should be passed in. TAKE2 indicates two pre-parsed arguments. Other options are TAKE1, which indicates one pre-parsed argument, FLAG, which indicates that the argument should be On or Off, and is passed in as a boolean flag, RAW_ARGS, which causes the server to give the command the raw, unparsed arguments (everything but the command name itself). There is also ITERATE, which means that the handler looks the same as TAKE1, but that if multiple arguments are present, it should be called multiple times, and finally ITERATE2, which indicates that the command handler looks like a TAKE2, but if more arguments are present, then it should be called multiple times, holding the first argument constant.
  • Finally, we have a string which describes the arguments that should be present. If the arguments in the actual config file are not as required, this string will be used to help give a more specific error message. (You can safely leave this NULL).

Finally, having set this all up, we have to use it. This is ultimately done in the module's handlers, specifically for its file-typing handler, which looks more or less like this; note that the per-directory configuration structure is extracted from the request_rec's per-directory configuration vector by using the ap_get_module_config function.

        int find_ct(request_rec *r)
{
int i;
char *fn = ap_pstrdup (r->pool, r->filename);
mime_dir_config *conf = (mime_dir_config *)
ap_get_module_config(r->per_dir_config, &mime_module);
char *type;

if (S_ISDIR(r->finfo.st_mode)) {
r->content_type = DIR_MAGIC_TYPE;
return OK;
}

if((i=ap_rind(fn,'.')) < 0) return DECLINED;
++i;

if ((type = ap_table_get (conf->encoding_types, &fn[i])))
{
r->content_encoding = type;

/* go back to previous extension to try to use it as a type */
fn[i-1] = '\0';
if((i=ap_rind(fn,'.')) < 0) return OK;
++i;
}

if ((type = ap_table_get (conf->forced_types, &fn[i])))
{
r->content_type = type;
}

return OK;

        }

Side notes -- per-server configuration, virtual servers, etc.

The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation function and a merge function, the latter being invoked where a virtual server has partially overridden the base server configuration, and a combined structure must be computed. (As with per-directory configuration, the default if no merge function is specified, and a module is configured in some virtual server, is that the base configuration is simply ignored).

The only substantial difference is that when a command needs to configure the per-server private module data, it needs to go to the cmd_parms data to get at it. Here's an example, from the alias module, which also indicates how a syntax error can be returned (note that the per-directory configuration argument to the command handler is declared as a dummy, since the module doesn't actually have per-directory config data):

char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
{
server_rec *s = cmd->server;
alias_server_conf *conf = (alias_server_conf *)
ap_get_module_config(s->module_config,&alias_module);
 alias_entry *new = ap_push_array (conf->redirects);

if (!ap_is_url (url)) return "Redirect to non-URL";

new->fake = f; new->real = url;
return NULL;
 }

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


API Changes in Apache HTTP Server 2.4 since 2.2 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

API Changes in Apache HTTP Server 2.4 since 2.2

This document describes changes to the Apache HTTPD API from version 2.2 to 2.4, that may be of interest to module/application developers and core hacks. As of the first GA release of the 2.4 branch API compatibility is preserved for the life of the 2.4 branch. (The VERSIONING description for the 2.4 release provides more information about API compatibility.)

API changes fall into two categories: APIs that are altogether new, and existing APIs that are expanded or changed. The latter are further divided into those where all changes are backwards-compatible (so existing modules can ignore them), and those that might require attention by maintainers. As with the transition from HTTPD 2.0 to 2.2, existing modules and applications will require recompiling and may call for some attention, but most should not require any substantial updating (although some may be able to take advantage of API changes to offer significant improvements).

For the purpose of this document, the API is split according to the public header files. These headers are themselves the reference documentation, and can be used to generate a browsable HTML reference with make docs.

Changed APIs

ap_expr (NEW!)

Introduces a new API to parse and evaluate boolean and algebraic expressions, including provision for a standard syntax and customised variants.

ap_listen (changed; backwards-compatible)

Introduces a new API to enable httpd child processes to serve different purposes.

ap_mpm (changed)

ap_mpm_run is replaced by a new mpm hook. Also ap_graceful_stop_signalled is lost, and ap_mpm_register_timed_callback is new.

ap_regex (changed)

In addition to the existing regexp wrapper, a new higher-level API ap_rxplus is now provided. This provides the capability to compile Perl-style expressions like s/regexp/replacement/flags and to execute them against arbitrary strings. Support for regexp backreferences is also added.

ap_slotmem (NEW!)

Introduces an API for modules to allocate and manage memory slots, most commonly for shared memory.

ap_socache (NEW!)

API to manage a shared object cache.

heartbeat (NEW!)

common structures for heartbeat modules

ap_parse_htaccess (changed)

The function signature for ap_parse_htaccess has been changed. A apr_table_t of individual directives allowed for override must now be passed (override remains).

http_config (changed)

  • Introduces per-module, per-directory loglevels, including macro wrappers.
  • New AP_DECLARE_MODULE macro to declare all modules.
  • New APLOG_USE_MODULE macro necessary for per-module loglevels in multi-file modules.
  • New API to retain data across module unload/load
  • New check_config hook
  • New ap_process_fnmatch_configs() function to process wildcards
  • Change ap_configfile_t, ap_cfg_getline(), ap_cfg_getc() to return error codes, and add ap_pcfg_strerror() for retrieving an error description.
  • Any config directive permitted in ACCESS_CONF context must now correctly handle being called from an .htaccess file via the new AllowOverrideList directive. ap_check_cmd_context() accepts a new flag NOT_IN_HTACCESS to detect this case.

http_core (changed)

  • REMOVED ap_default_type, ap_requires, all 2.2 authnz API
  • Introduces Optional Functions for logio and authnz
  • New function ap_get_server_name_for_url to support IPv6 literals.
  • New function ap_register_errorlog_handler to register error log format string handlers.
  • Arguments of error_log hook have changed. Declaration has moved to http_core.h.
  • New function ap_state_query to determine if the server is in the initial configuration preflight phase or not. This is both easier to use and more correct than the old method of creating a pool userdata entry in the process pool.
  • New function ap_get_conn_socket to get the socket descriptor for a connection. This should be used instead of accessing the core connection config directly.

httpd (changed)

  • Introduce per-directory, per-module loglevel
  • New loglevels APLOG_TRACEn
  • Introduce errorlog ids for requests and connections
  • Support for mod_request kept_body
  • Support buffering filter data for async requests
  • New CONN_STATE values
  • Function changes: ap_escape_html updated; ap_unescape_all, ap_escape_path_segment_buffer
  • Modules that load other modules later than the EXEC_ON_READ config reading stage need to call ap_reserve_module_slots() or ap_reserve_module_slots_directive() in their pre_config hook.
  • The useragent IP address per request can now be tracked independently of the client IP address of the connection, for support of deployments with load balancers.

http_log (changed)

  • Introduce per-directory, per-module loglevel
  • New loglevels APLOG_TRACEn
  • ap_log_*error become macro wrappers (backwards-compatible if APLOG_MARK macro is used, except that is no longer possible to use #ifdef inside the argument list)
  • piped logging revamped
  • module_index added to error_log hook
  • new function: ap_log_command_line

http_request (changed)

  • New auth_internal API and auth_provider API
  • New EOR bucket type
  • New function ap_process_async_request
  • New flags AP_AUTH_INTERNAL_PER_CONF and AP_AUTH_INTERNAL_PER_URI
  • New access_checker_ex hook to apply additional access control and/or bypass authentication.
  • New functions ap_hook_check_access_ex, ap_hook_check_access, ap_hook_check_authn, ap_hook_check_authz which accept AP_AUTH_INTERNAL_PER_* flags
  • DEPRECATED direct use of ap_hook_access_checker, access_checker_ex, ap_hook_check_user_id, ap_hook_auth_checker

When possible, registering all access control hooks (including authentication and authorization hooks) using AP_AUTH_INTERNAL_PER_CONF is recommended. If all modules' access control hooks are registered with this flag, then whenever the server handles an internal sub-request that matches the same set of access control configuration directives as the initial request (which is the common case), it can avoid invoking the access control hooks another time.

If your module requires the old behavior and must perform access control checks on every sub-request with a different URI from the initial request, even if that URI matches the same set of access control configuration directives, then use AP_AUTH_INTERNAL_PER_URI.

mod_auth (NEW!)

Introduces the new provider framework for authn and authz

mod_cache (changed)

Introduces a commit_entity() function to the cache provider interface, allowing atomic writes to cache. Add a cache_status() hook to report the cache decision. All private structures and functions were removed.

mod_core (NEW!)

This introduces low-level APIs to send arbitrary headers, and exposes functions to handle HTTP OPTIONS and TRACE.

mod_cache_disk (changed)

Changes the disk format of the disk cache to support atomic cache updates without locking. The device/inode pair of the body file is embedded in the header file, allowing confirmation that the header and body belong to one another.

mod_disk_cache (renamed)

The mod_disk_cache module has been renamed to mod_cache_disk in order to be consistent with the naming of other modules within the server.

mod_request (NEW!)

The API for mod_request, to make input data available to multiple application/handler modules where required, and to parse HTML form data.

mpm_common (changed)

  • REMOVES: accept, lockfile, lock_mech, set_scoreboard (locking uses the new ap_mutex API)
  • NEW API to drop privileges (delegates this platform-dependent function to modules)
  • NEW Hooks: mpm_query, timed_callback, and get_name
  • CHANGED interfaces: monitor hook, ap_reclaim_child_processes, ap_relieve_child_processes

scoreboard (changed)

ap_get_scoreboard_worker is made non-backwards-compatible as an alternative version is introduced. Additional proxy_balancer support. Child status stuff revamped.

util_cookies (NEW!)

Introduces a new API for managing HTTP Cookies.

util_ldap (changed)

no description available

util_mutex (NEW!)

A wrapper for APR proc and global mutexes in httpd, providing common configuration for the underlying mechanism and location of lock files.

util_script (changed)

NEW: ap_args_to_table

util_time (changed)

NEW: ap_recent_ctime_ex

Specific information on upgrading modules from 2.2

Logging

In order to take advantage of per-module loglevel configuration, any source file that calls the ap_log_* functions should declare which module it belongs to. If the module's module_struct is called foo_module, the following code can be used to remain backward compatible with HTTPD 2.0 and 2.2:

#include <http_log.h>

#ifdef APLOG_USE_MODULE
APLOG_USE_MODULE(foo);
#endif

Note: This is absolutely required for C++-language modules. It can be skipped for C-language modules, though that breaks module-specific log level support for files without it.

The number of parameters of the ap_log_* functions and the definition of APLOG_MARK has changed. Normally, the change is completely transparent. However, changes are required if a module uses APLOG_MARK as a parameter to its own functions or if a module calls ap_log_* without passing APLOG_MARK. A module which uses wrappers around ap_log_* typically uses both of these constructs.

The easiest way to change code which passes APLOG_MARK to its own functions is to define and use a different macro that expands to the parameters required by those functions, as APLOG_MARK should only be used when calling ap_log_* directly. In this way, the code will remain compatible with HTTPD 2.0 and 2.2.

Code which calls ap_log_* without passing APLOG_MARK will necessarily differ between 2.4 and earlier releases, as 2.4 requires a new third argument, APLOG_MODULE_INDEX.

/* code for httpd 2.0/2.2 */
ap_log_perror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

/* code for httpd 2.4 */
ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

ap_log_*error are now implemented as macros. This means that it is no longer possible to use #ifdef inside the argument list of ap_log_*error, as this would cause undefined behavor according to C99.

A server_rec pointer must be passed to ap_log_error() when called after startup. This was always appropriate, but there are even more limitations with a NULL server_rec in 2.4 than in previous releases. Beginning with 2.3.12, the global variable ap_server_conf can always be used as the server_rec parameter, as it will be NULL only when it is valid to pass NULL to ap_log_error(). ap_server_conf should be used only when a more appropriate server_rec is not available.

Consider the following changes to take advantage of the new APLOG_TRACE1..8 log levels:

  • Check current use of APLOG_DEBUG and consider if one of the APLOG_TRACEn levels is more appropriate.
  • If your module currently has a mechanism for configuring the amount of debug logging which is performed, consider eliminating that mechanism and relying on the use of different APLOG_TRACEn levels. If expensive trace processing needs to be bypassed depending on the configured log level, use the APLOGtracen and APLOGrtracen macros to first check if tracing is enabled.

Modules sometimes add process id and/or thread id to their log messages. These ids are now logged by default, so it may not be necessary for the module to log them explicitly. (Users may remove them from the error log format, but they can be instructed to add it back if necessary for problem diagnosis.)

If your module uses these existing APIs...

ap_default_type()
This is no longer available; Content-Type must be configured explicitly or added by the application.
ap_get_server_name()
If the returned server name is used in a URL, use ap_get_server_name_for_url() instead. This new function handles the odd case where the server name is an IPv6 literal address.
ap_get_server_version()
For logging purposes, where detailed information is appropriate, use ap_get_server_description(). When generating output, where the amount of information should be configurable by ServerTokens, use ap_get_server_banner().
ap_graceful_stop_signalled()
Replace with a call to ap_mpm_query(AP_MPMQ_MPM_STATE) and checking for state AP_MPMQ_STOPPING.
ap_max_daemons_limit, ap_my_generation, and ap_threads_per_child
Use ap_mpm_query() query codes AP_MPMQ_MAX_DAEMON_USED, AP_MPMQ_GENERATION, and AP_MPMQ_MAX_THREADS, respectively.
ap_mpm_query()
Ensure that it is not used until after the register-hooks hook has completed. Otherwise, an MPM built as a DSO would not have had a chance to enable support for this function.
ap_requires()
The core server now provides better infrastructure for handling Require configuration. Register an auth provider function for each supported entity using ap_register_auth_provider(). The function will be called as necessary during Require processing. (Consult bundled modules for detailed examples.)
ap_server_conf->process->pool userdata
Optional:
  • If your module uses this to determine which pass of the startup hooks is being run, use ap_state_query(AP_SQ_MAIN_STATE).
  • If your module uses this to maintain data across the unloading and reloading of your module, use ap_retained_data_create() and ap_retained_data_get().
apr_global_mutex_create(), apr_proc_mutex_create()
Optional: See ap_mutex_register(), ap_global_mutex_create(), and ap_proc_mutex_create(); these allow your mutexes to be configurable with the Mutex directive; you can also remove any configuration mechanisms in your module for such mutexes
CORE_PRIVATE
This is now unnecessary and ignored.
dav_new_error() and dav_new_error_tag()
Previously, these assumed that errno contained information describing the failure. Now, an apr_status_t parameter must be provided. Pass 0/APR_SUCCESS if there is no such error information, or a valid apr_status_t value otherwise.
mpm_default.h, DEFAULT_LOCKFILE, DEFAULT_THREAD_LIMIT, DEFAULT_PIDLOG, etc.
The header file and most of the default configuration values set in it are no longer visible to modules. (Most can still be overridden at build time.) DEFAULT_PIDLOG and DEFAULT_REL_RUNTIMEDIR are now universally available via ap_config.h.
unixd_config
This has been renamed to ap_unixd_config.
unixd_setup_child()
This has been renamed to ap_unixd_setup_child(), but most callers should call the added ap_run_drop_privileges() hook.
conn_rec->remote_ip and conn_rec->remote_addr
These fields have been renamed in order to distinguish between the client IP address of the connection and the useragent IP address of the request (potentially overridden by a load balancer or proxy). References to either of these fields must be updated with one of the following options, as appropriate for the module:
  • When you require the IP address of the user agent, which might be connected directly to the server, or might optionally be separated from the server by a transparent load balancer or proxy, use request_rec->useragent_ip and request_rec->useragent_addr.
  • When you require the IP address of the client that is connected directly to the server, which might be the useragent or might be the load balancer or proxy itself, use conn_rec->client_ip and conn_rec->client_addr.

If your module interfaces with this feature...

suEXEC
Optional: If your module logs an error when ap_unixd_config.suexec_enabled is 0, also log the value of the new field suexec_disabled_reason, which contains an explanation of why it is not available.
Extended status data in the scoreboard
In previous releases, ExtendedStatus had to be set to On, which in turn required that mod_status was loaded. In 2.4, just set ap_extended_status to 1 in a pre-config hook and the extended status data will be available.

Does your module...

Parse query args
Consider if ap_args_to_table() would be helpful.
Parse form data...
Use ap_parse_form_data().
Check for request header fields Content-Length and Transfer-Encoding to see if a body was specified
Use ap_request_has_body().
Implement cleanups which clear pointer variables
Use ap_pool_cleanup_set_null().
Create run-time files such as shared memory files, pid files, etc.
Use ap_runtime_dir_relative() so that the global configuration for the location of such files, either by the DEFAULT_REL_RUNTIMEDIR compile setting or the DefaultRuntimeDir directive, will be respected. Apache httpd 2.4.2 and above.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Developing modules for the Apache HTTP Server 2.4 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer

Developing modules for the Apache HTTP Server 2.4

This document explains how you can develop modules for the Apache HTTP Server 2.4

See also

  • Request Processing in Apache 2.4
  • Apache 2.x Hook Functions

Introduction

What we will be discussing in this document

This document will discuss how you can create modules for the Apache HTTP Server 2.4, by exploring an example module called mod_example. In the first part of this document, the purpose of this module will be to calculate and print out various digest values for existing files on your web server, whenever we access the URL http://hostname/filename.sum. For instance, if we want to know the MD5 digest value of the file located at http://www.example.com/index.html, we would visit http://www.example.com/index.html.sum.

In the second part of this document, which deals with configuration directive and context awareness, we will be looking at a module that simply writes out its own configuration to the client.

Prerequisites

First and foremost, you are expected to have a basic knowledge of how the C programming language works. In most cases, we will try to be as pedagogical as possible and link to documents describing the functions used in the examples, but there are also many cases where it is necessary to either just assume that "it works" or do some digging yourself into what the hows and whys of various function calls.

Lastly, you will need to have a basic understanding of how modules are loaded and configured in the Apache HTTP Server, as well as how to get the headers for Apache if you do not have them already, as these are needed for compiling new modules.

Compiling your module

To compile the source code we are building in this document, we will be using APXS. Assuming your source file is called mod_example.c, compiling, installing and activating the module is as simple as:

apxs -i -a -c mod_example.c

Defining a module

Module name tags
Every module starts with the same declaration, or name tag if you will, that defines a module as a separate entity within Apache:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    create_dir_conf, /* Per-directory configuration handler */
    merge_dir_conf,  /* Merge handler for per-directory configurations */
    create_svr_conf, /* Per-server configuration handler */
    merge_svr_conf,  /* Merge handler for per-server configurations */
    directives,      /* Any directives we may have for httpd */
    register_hooks   /* Our hook registering function */
};

This bit of code lets the server know that we have now registered a new module in the system, and that its name is example_module. The name of the module is used primarily for two things:

  • Letting the server know how to load the module using the LoadModule
  • Setting up a namespace for the module to use in configurations

For now, we're only concerned with the first purpose of the module name, which comes into play when we need to load the module:

LoadModule example_module modules/mod_example.so

In essence, this tells the server to open up mod_example.so and look for a module called example_module.

Within this name tag of ours is also a bunch of references to how we would like to handle things: Which directives do we respond to in a configuration file or .htaccess, how do we operate within specific contexts, and what handlers are we interested in registering with the Apache HTTP service. We'll return to all these elements later in this document.

Getting started: Hooking into the server

An introduction to hooks

When handling requests in Apache HTTP Server 2.4, the first thing you will need to do is create a hook into the request handling process. A hook is essentially a message telling the server that you are willing to either serve or at least take a glance at certain requests given by clients. All handlers, whether it's mod_rewrite, mod_authn_*, mod_proxy and so on, are hooked into specific parts of the request process. As you are probably aware, modules serve different purposes; Some are authentication/authorization handlers, others are file or script handlers while some third modules rewrite URIs or proxies content. Furthermore, in the end, it is up to the user of the server how and when each module will come into place. Thus, the server itself does not presume to know which module is responsible for handling a specific request, and will ask each module whether they have an interest in a given request or not. It is then up to each module to either gently decline serving a request, accept serving it or flat out deny the request from being served, as authentication/authorization modules do:
Hook handling in httpd
To make it a bit easier for handlers such as our mod_example to know whether the client is requesting content we should handle or not, the server has directives for hinting to modules whether their assistance is needed or not. Two of these are AddHandler and SetHandler. Let's take a look at an example using AddHandler. In our example case, we want every request ending with .sum to be served by mod_example, so we'll add a configuration directive that tells the server to do just that:

AddHandler example-handler .sum

What this tells the server is the following: Whenever we receive a request for a URI ending in .sum, we are to let all modules know that we are looking for whoever goes by the name of "example-handler" . Thus, when a request is being served that ends in .sum, the server will let all modules know, that this request should be served by "example-handler ". As you will see later, when we start building mod_example, we will check for this handler tag relayed by AddHandler and reply to the server based on the value of this tag.

Hooking into httpd

To begin with, we only want to create a simple handler, that replies to the client browser when a specific URL is requested, so we won't bother setting up configuration handlers and directives just yet. Our initial module definition will look like this:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,
    NULL,
    NULL,
    NULL,
    NULL,
    register_hooks   /* Our hook registering function */
};

This lets the server know that we are not interested in anything fancy, we just want to hook onto the requests and possibly handle some of them.

The reference in our example declaration, register_hooks is the name of a function we will create to manage how we hook onto the request process. In this example module, the function has just one purpose; To create a simple hook that gets called after all the rewrites, access control etc has been handled. Thus, we will let the server know, that we want to hook into its process as one of the last modules:

static void register_hooks(apr_pool_t *pool)
{
    /* Create a hook in the request handler, so we get called when a request arrives */
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

The example_handler reference is the function that will handle the request. We will discuss how to create a handler in the next chapter.

Other useful hooks

Hooking into the request handling phase is but one of many hooks that you can create. Some other ways of hooking are:

  • ap_hook_child_init: Place a hook that executes when a child process is spawned (commonly used for initializing modules after the server has forked)
  • ap_hook_pre_config: Place a hook that executes before any configuration data has been read (very early hook)
  • ap_hook_post_config: Place a hook that executes after configuration has been parsed, but before the server has forked
  • ap_hook_translate_name: Place a hook that executes when a URI needs to be translated into a filename on the server (think mod_rewrite)
  • ap_hook_quick_handler: Similar to ap_hook_handler, except it is run before any other request hooks (translation, auth, fixups etc)
  • ap_hook_log_transaction: Place a hook that executes when the server is about to add a log entry of the current request

Building a handler

A handler is essentially a function that receives a callback when a request to the server is made. It is passed a record of the current request (how it was made, which headers and requests were passed along, who's giving the request and so on), and is put in charge of either telling the server that it's not interested in the request or handle the request with the tools provided.

A simple "Hello, world!" handler

Let's start off by making a very simple request handler that does the following:

  1. Check that this is a request that should be served by "example-handler"
  2. Set the content type of our output to text/html
  3. Write "Hello, world!" back to the client browser
  4. Let the server know that we took care of this request and everything went fine

In C code, our example handler will now look like this:

static int example_handler(request_rec *r)
{
    /* First off, we need to check if this is a call for the "example-handler" handler.
     * If it is, we accept it and do our things, if not, we simply return DECLINED,
     * and the server will try somewhere else.
     */
    if (!r->handler || strcmp(r->handler, "example-handler")) return (DECLINED);

    /* Now that we are handling this request, we'll write out "Hello, world!" to the client.
     * To do so, we must first set the appropriate content type, followed by our output.
     */
    ap_set_content_type(r, "text/html");
    ap_rprintf(r, "Hello, world!");

    /* Lastly, we must tell the server that we took care of this request and everything went fine.
     * We do so by simply returning the value OK to the server.
     */
    return OK;
}

Now, we put all we have learned together and end up with a program that looks like mod_example_1.c . The functions used in this example will be explained later in the section "Some useful functions you should know".

The request_rec structure

The most essential part of any request is the request record . In a call to a handler function, this is represented by the request_rec* structure passed along with every call that is made. This struct, typically just referred to as r in modules, contains all the information you need for your module to fully process any HTTP request and respond accordingly.

Some key elements of the request_rec structure are:

  • r->handler (char*): Contains the name of the handler the server is currently asking to do the handling of this request
  • r->method (char*): Contains the HTTP method being used, f.x. GET or POST
  • r->filename (char*): Contains the translated filename the client is requesting
  • r->args (char*): Contains the query string of the request, if any
  • r->headers_in (apr_table_t*): Contains all the headers sent by the client
  • r->connection (conn_rec*): A record containing information about the current connection
  • r->user (char*): If the URI requires authentication, this is set to the username provided
  • r->useragent_ip (char*): The IP address of the client connecting to us
  • r->pool (apr_pool_t*): The memory pool of this request. We'll discuss this in the "Memory management" chapter.

A complete list of all the values contained within the request_rec structure can be found in the httpd.h header file or at http://ci.apache.org/projects/httpd/trunk/doxygen/structrequest__rec.html.

Let's try out some of these variables in another example handler:

static int example_handler(request_rec *r)
{
    /* Set the appropriate content type */
    ap_set_content_type(r, "text/html");

    /* Print out the IP address of the client connecting to us: */
    ap_rprintf(r, "<h2>Hello, %s!</h2>", r->useragent_ip);

    /* If we were reached through a GET or a POST request, be happy, else sad. */
    if ( !strcmp(r->method, "POST") || !strcmp(r->method, "GET") ) {
        ap_rputs("You used a GET or a POST method, that makes us happy!<br/>", r);
    }
    else {
        ap_rputs("You did not use POST or GET, that makes us sad :(<br/>", r);
    }

    /* Lastly, if there was a query string, let's print that too! */
    if (r->args) {
        ap_rprintf(r, "Your query string was: %s", r->args);
    }
    return OK;
}

Return values

Apache relies on return values from handlers to signify whether a request was handled or not, and if so, whether the request went well or not. If a module is not interested in handling a specific request, it should always return the value DECLINED. If it is handling a request, it should either return the generic value OK, or a specific HTTP status code, for example:

static int example_handler(request_rec *r)
{
    /* Return 404: Not found */
    return HTTP_NOT_FOUND;
}

Returning OK or a HTTP status code does not necessarily mean that the request will end. The server may still have other handlers that are interested in this request, for instance the logging modules which, upon a successful request, will write down a summary of what was requested and how it went. To do a full stop and prevent any further processing after your module is done, you can return the value DONE to let the server know that it should cease all activity on this request and carry on with the next, without informing other handlers.
General response codes:

  • DECLINED: We are not handling this request
  • OK: We handled this request and it went well
  • DONE: We handled this request and the server should just close this thread without further processing

HTTP specific return codes (excerpt):

  • HTTP_OK (200): Request was okay
  • HTTP_MOVED_PERMANENTLY (301): The resource has moved to a new URL
  • HTTP_UNAUTHORIZED (401): Client is not authorized to visit this page
  • HTTP_FORBIDDEN (403): Permission denied
  • HTTP_NOT_FOUND (404): File not found
  • HTTP_INTERNAL_SERVER_ERROR (500): Internal server error (self explanatory)

Some useful functions you should know

  • ap_rputs(const char *string, request_rec *r):
    Sends a string of text to the client. This is a shorthand version of ap_rwrite.
    ap_rputs("Hello, world!", r);
  • ap_rprintf:
    This function works just like printf, except it sends the result to the client.
    ap_rprintf(r, "Hello, %s!", r->useragent_ip);
  • ap_set_content_type(request_rec *r, const char *type):
    Sets the content type of the output you are sending.
    ap_set_content_type(r, "text/plain"); /* force a raw text output */

Memory management

Managing your resources in Apache HTTP Server 2.4 is quite easy, thanks to the memory pool system. In essence, each server, connection and request have their own memory pool that gets cleaned up when its scope ends, e.g. when a request is done or when a server process shuts down. All your module needs to do is latch onto this memory pool, and you won't have to worry about having to clean up after yourself - pretty neat, huh?

In our module, we will primarily be allocating memory for each request, so it's appropriate to use the r->pool reference when creating new objects. A few of the functions for allocating memory within a pool are:

  • void* apr_palloc( apr_pool_t *p, apr_size_t size): Allocates size number of bytes in the pool for you
  • void* apr_pcalloc( apr_pool_t *p, apr_size_t size): Allocates size number of bytes in the pool for you and sets all bytes to 0
  • char* apr_pstrdup( apr_pool_t *p, const char *s): Creates a duplicate of the string s. This is useful for copying constant values so you can edit them
  • char* apr_psprintf( apr_pool_t *p, const char *fmt, ...): Similar to sprintf, except the server supplies you with an appropriately allocated target variable

Let's put these functions into an example handler:

static int example_handler(request_rec *r)
{
    const char *original = "You can't edit this!";
    char *copy;
    int *integers;

    /* Allocate space for 10 integer values and set them all to zero. */
    integers = apr_pcalloc(r->pool, sizeof(int)*10);

    /* Create a copy of the 'original' variable that we can edit. */
    copy = apr_pstrdup(r->pool, original);
    return OK;
}

This is all well and good for our module, which won't need any pre-initialized variables or structures. However, if we wanted to initialize something early on, before the requests come rolling in, we could simply add a call to a function in our register_hooks function to sort it out:

static void register_hooks(apr_pool_t *pool)
{
    /* Call a function that initializes some stuff */
    example_init_function(pool);
    /* Create a hook in the request handler, so we get called when a request arrives */
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

In this pre-request initialization function we would not be using the same pool as we did when allocating resources for request-based functions. Instead, we would use the pool given to us by the server for allocating memory on a per-process based level.

Parsing request data

In our example module, we would like to add a feature, that checks which type of digest, MD5 or SHA1 the client would like to see. This could be solved by adding a query string to the request. A query string is typically comprised of several keys and values put together in a string, for instance valueA=yes&valueB=no&valueC=maybe. It is up to the module itself to parse these and get the data it requires. In our example, we'll be looking for a key called digest, and if set to md5, we'll produce an MD5 digest, otherwise we'll produce a SHA1 digest.

Since the introduction of Apache HTTP Server 2.4, parsing request data from GET and POST requests have never been easier. All we require to parse both GET and POST data is four simple lines:

apr_table_t *GET;
apr_array_header_t*POST;

ap_args_to_table(r, &GET);

ap_parse_form_data(r, NULL, &POST, -1, 8192);

In our specific example module, we're looking for the digest value from the query string, which now resides inside a table called GET. To extract this value, we need only perform a simple operation:

/* Get the "digest" key from the query string, if any. */
const char *digestType = apr_table_get(GET, "digest");

/* If no key was returned, we will set a default value instead. */
if (!digestType) digestType = "sha1";

The structures used for the POST and GET data are not exactly the same, so if we were to fetch a value from POST data instead of the query string, we would have to resort to a few more lines, as outlined in this example in the last chapter of this document.

Making an advanced handler

Now that we have learned how to parse form data and manage our resources, we can move on to creating an advanced version of our module, that spits out the MD5 or SHA1 digest of files:

static int example_handler(request_rec *r)
{
    int rc, exists;
    apr_finfo_t finfo;
    apr_file_t *file;
    char *filename;
    char buffer[256];
    apr_size_t readBytes;
    int n;
    apr_table_t *GET;
    apr_array_header_t *POST;
    const char *digestType;

    /* Check that the "example-handler" handler is being called. */
    if (!r->handler || strcmp(r->handler, "example-handler")) return (DECLINED);

    /* Figure out which file is being requested by removing the .sum from it */
    filename = apr_pstrdup(r->pool, r->filename);
    filename[strlen(filename)-4] = 0; /* Cut off the last 4 characters. */

    /* Figure out if the file we request a sum on exists and isn't a directory */
    rc = apr_stat(&finfo, filename, APR_FINFO_MIN, r->pool);
    if (rc == APR_SUCCESS) {
        exists =
        (
            (finfo.filetype != APR_NOFILE)
        &&  !(finfo.filetype & APR_DIR)
        );
        if (!exists) return HTTP_NOT_FOUND; /* Return a 404 if not found. */
    }
    /* If apr_stat failed, we're probably not allowed to check this file. */
    else return HTTP_FORBIDDEN;

    /* Parse the GET and, optionally, the POST data sent to us */

    ap_args_to_table(r, &GET);
    ap_parse_form_data(r, NULL, &POST, -1, 8192);

    /* Set the appropriate content type */
    ap_set_content_type(r, "text/html");

    /* Print a title and some general information */
    ap_rprintf(r, "<h2>Information on %s:</h2>", filename);
    ap_rprintf(r, "<b>Size:</b> %u bytes<br/>", finfo.size);

    /* Get the digest type the client wants to see */
    digestType = apr_table_get(GET, "digest");
    if (!digestType) digestType = "MD5";

    rc = apr_file_open(&file, filename, APR_READ, APR_OS_DEFAULT, r->pool);
    if (rc == APR_SUCCESS) {

        /* Are we trying to calculate the MD5 or the SHA1 digest? */
        if (!strcasecmp(digestType, "md5")) {
            /* Calculate the MD5 sum of the file */
            union {
                char      chr[16];
                uint32_t  num[4];
            } digest;
            apr_md5_ctx_t md5;
            apr_md5_init(&md5);
            readBytes = 256;
            while ( apr_file_read(file, buffer, &readBytes) == APR_SUCCESS ) {
                apr_md5_update(&md5, buffer, readBytes);
            }
            apr_md5_final(digest.chr, &md5);

            /* Print out the MD5 digest */
            ap_rputs("<b>MD5: </b><code>", r);
            for (n = 0; n < APR_MD5_DIGESTSIZE/4; n++) {
                ap_rprintf(r, "%08x", digest.num[n]);
            }
            ap_rputs("</code>", r);
            /* Print a link to the SHA1 version */
            ap_rputs("<br/><a href='?digest=sha1'>View the SHA1 hash instead</a>", r);
        }
        else {
            /* Calculate the SHA1 sum of the file */
            union {
                char      chr[20];
                uint32_t  num[5];
            } digest;
            apr_sha1_ctx_t sha1;
            apr_sha1_init(&sha1);
            readBytes = 256;
            while ( apr_file_read(file, buffer, &readBytes) == APR_SUCCESS ) {
                apr_sha1_update(&sha1, buffer, readBytes);
            }
            apr_sha1_final(digest.chr, &sha1);

            /* Print out the SHA1 digest */
            ap_rputs("<b>SHA1: </b><code>", r);
            for (n = 0; n < APR_SHA1_DIGESTSIZE/4; n++) {
                ap_rprintf(r, "%08x", digest.num[n]);
            }
            ap_rputs("</code>", r);

            /* Print a link to the MD5 version */
            ap_rputs("<br/><a href='?digest=md5'>View the MD5 hash instead</a>", r);
        }
        apr_file_close(file);

    }
    /* Let the server know that we responded to this request. */
    return OK;
}

This version in its entirety can be found here: mod_example_2.c.

Adding configuration options

In this next segment of this document, we will turn our eyes away from the digest module and create a new example module, whose only function is to write out its own configuration. The purpose of this is to examine how the server works with configuration, and what happens when you start writing advanced configurations for your modules.

An introduction to configuration directives

If you are reading this, then you probably already know what a configuration directive is. Simply put, a directive is a way of telling an individual module (or a set of modules) how to behave, such as these directives control how mod_rewrite works:

RewriteEngine On
RewriteCond "%{REQUEST_URI}" "^/foo/bar"
RewriteRule "^/foo/bar/(.*)$" "/foobar?page=$1"

Each of these configuration directives are handled by a separate function, that parses the parameters given and sets up a configuration accordingly.

Making an example configuration

To begin with, we'll create a basic configuration in C-space:

typedef struct {
    int         enabled;      /* Enable or disable our module */
    const char *path;         /* Some path to...something */
    int         typeOfAction; /* 1 means action A, 2 means action B and so on */
} example_config;

Now, let's put this into perspective by creating a very small module that just prints out a hard-coded configuration. You'll notice that we use the register_hooks function for initializing the configuration values to their defaults:

typedef struct {
    int         enabled;      /* Enable or disable our module */
    const char *path;         /* Some path to...something */
    int         typeOfAction; /* 1 means action A, 2 means action B and so on */
} example_config;

static example_config config;

static int example_handler(request_rec *r)
{
    if (!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);
    ap_set_content_type(r, "text/plain");
    ap_rprintf(r, "Enabled: %u\n", config.enabled);
    ap_rprintf(r, "Path: %s\n", config.path);
    ap_rprintf(r, "TypeOfAction: %x\n", config.typeOfAction);
    return OK;
}

static void register_hooks(apr_pool_t *pool)
{
    config.enabled = 1;
    config.path = "/foo/bar";
    config.typeOfAction = 0x00;
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

/* Define our module as an entity and assign a function for registering hooks  */

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,            /* Per-directory configuration handler */
    NULL,            /* Merge handler for per-directory configurations */
    NULL,            /* Per-server configuration handler */
    NULL,            /* Merge handler for per-server configurations */
    NULL,            /* Any directives we may have for httpd */
    register_hooks   /* Our hook registering function */
};

So far so good. To access our new handler, we could add the following to our configuration:

<Location "/example">
    SetHandler example-handler
</Location>

When we visit, we'll see our current configuration being spit out by our module.

Registering directives with the server

What if we want to change our configuration, not by hard-coding new values into the module, but by using either the httpd.conf file or possibly a .htaccess file? It's time to let the server know that we want this to be possible. To do so, we must first change our name tag to include a reference to the configuration directives we want to register with the server:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,               /* Per-directory configuration handler */
    NULL,               /* Merge handler for per-directory configurations */
    NULL,               /* Per-server configuration handler */
    NULL,               /* Merge handler for per-server configurations */
    example_directives, /* Any directives we may have for httpd */
    register_hooks      /* Our hook registering function */
};

This will tell the server that we are now accepting directives from the configuration files, and that the structure called example_directives holds information on what our directives are and how they work. Since we have three different variables in our module configuration, we will add a structure with three directives and a NULL at the end:

static const command_rec        example_directives[] =
{
    AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, RSRC_CONF, "Enable or disable mod_example"),
    AP_INIT_TAKE1("examplePath", example_set_path, NULL, RSRC_CONF, "The path to whatever"),
    AP_INIT_TAKE2("exampleAction", example_set_action, NULL, RSRC_CONF, "Special action value!"),
    { NULL }
};

Directives structure
As you can see, each directive needs at least 5 parameters set:

  1. AP_INIT_TAKE1: This is a macro that tells the server that this directive takes one and only one argument. If we required two arguments, we could use the macro AP_INIT_TAKE2 and so on (refer to httpd_conf.h for more macros).
  2. exampleEnabled: This is the name of our directive. More precisely, it is what the user must put in his/her configuration in order to invoke a configuration change in our module.
  3. example_set_enabled: This is a reference to a C function that parses the directive and sets the configuration accordingly. We will discuss how to make this in the following paragraph.
  4. RSRC_CONF: This tells the server where the directive is permitted. We'll go into details on this value in the later chapters, but for now, RSRC_CONF means that the server will only accept these directives in a server context.
  5. "Enable or disable....": This is simply a brief description of what the directive does.

(The "missing" parameter in our definition, which is usually set to NULL, is an optional function that can be run after the initial function to parse the arguments have been run. This is usually omitted, as the function for verifying arguments might as well be used to set them.)

The directive handler function

Now that we have told the server to expect some directives for our module, it's time to make a few functions for handling these. What the server reads in the configuration file(s) is text, and so naturally, what it passes along to our directive handler is one or more strings, that we ourselves need to recognize and act upon. You'll notice, that since we set our exampleAction directive to accept two arguments, its C function also has an additional parameter defined:

/* Handler for the "exampleEnabled" directive */
const char *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg)
{
    if(!strcasecmp(arg, "on")) config.enabled = 1;
    else config.enabled = 0;
    return NULL;
}

/* Handler for the "examplePath" directive */
const char *example_set_path(cmd_parms *cmd, void *cfg, const char *arg)
{
    config.path = arg;
    return NULL;
}

/* Handler for the "exampleAction" directive */
/* Let's pretend this one takes one argument (file or db), and a second (deny or allow), */
/* and we store it in a bit-wise manner. */
const char *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2)
{
    if(!strcasecmp(arg1, "file")) config.typeOfAction = 0x01;
    else config.typeOfAction = 0x02;

    if(!strcasecmp(arg2, "deny")) config.typeOfAction += 0x10;
    else config.typeOfAction += 0x20;
    return NULL;
}

Putting it all together

Now that we have our directives set up, and handlers configured for them, we can assemble our module into one big file:

/* mod_example_config_simple.c: */
#include <stdio.h>
#include "apr_hash.h"
#include "ap_config.h"
#include "ap_provider.h"
#include "httpd.h"
#include "http_core.h"
#include "http_config.h"
#include "http_log.h"
#include "http_protocol.h"
#include "http_request.h"

/*
 ==============================================================================
 Our configuration prototype and declaration:
 ==============================================================================
 */
typedef struct {
    int         enabled;      /* Enable or disable our module */
    const char *path;         /* Some path to...something */
    int         typeOfAction; /* 1 means action A, 2 means action B and so on */
} example_config;

static example_config config;

/*
 ==============================================================================
 Our directive handlers:
 ==============================================================================
 */
/* Handler for the "exampleEnabled" directive */
const char *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg)
{
    if(!strcasecmp(arg, "on")) config.enabled = 1;
    else config.enabled = 0;
    return NULL;
}

/* Handler for the "examplePath" directive */
const char *example_set_path(cmd_parms *cmd, void *cfg, const char *arg)
{
    config.path = arg;
    return NULL;
}

/* Handler for the "exampleAction" directive */
/* Let's pretend this one takes one argument (file or db), and a second (deny or allow), */
/* and we store it in a bit-wise manner. */
const char *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2)
{
    if(!strcasecmp(arg1, "file")) config.typeOfAction = 0x01;
    else config.typeOfAction = 0x02;

    if(!strcasecmp(arg2, "deny")) config.typeOfAction += 0x10;
    else config.typeOfAction += 0x20;
    return NULL;
}

/*
 ==============================================================================
 The directive structure for our name tag:
 ==============================================================================
 */
static const command_rec        example_directives[] =
{
    AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, RSRC_CONF, "Enable or disable mod_example"),
    AP_INIT_TAKE1("examplePath", example_set_path, NULL, RSRC_CONF, "The path to whatever"),
    AP_INIT_TAKE2("exampleAction", example_set_action, NULL, RSRC_CONF, "Special action value!"),
    { NULL }
};
/*
 ==============================================================================
 Our module handler:
 ==============================================================================
 */
static int example_handler(request_rec *r)
{
    if(!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);
    ap_set_content_type(r, "text/plain");
    ap_rprintf(r, "Enabled: %u\n", config.enabled);
    ap_rprintf(r, "Path: %s\n", config.path);
    ap_rprintf(r, "TypeOfAction: %x\n", config.typeOfAction);
    return OK;
}

/*
 ==============================================================================
 The hook registration function (also initializes the default config values):
 ==============================================================================
 */
static void register_hooks(apr_pool_t *pool)
{
    config.enabled = 1;
    config.path = "/foo/bar";
    config.typeOfAction = 3;
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}
/*
 ==============================================================================
 Our module name tag:
 ==============================================================================
 */
module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    NULL,               /* Per-directory configuration handler */
    NULL,               /* Merge handler for per-directory configurations */
    NULL,               /* Per-server configuration handler */
    NULL,               /* Merge handler for per-server configurations */
    example_directives, /* Any directives we may have for httpd */
    register_hooks      /* Our hook registering function */
};

In our httpd.conf file, we can now change the hard-coded configuration by adding a few lines:

ExampleEnabled On
ExamplePath "/usr/bin/foo"
ExampleAction file allow

And thus we apply the configuration, visit /example on our web site, and we see the configuration has adapted to what we wrote in our configuration file.

Context aware configurations

Introduction to context aware configurations

In Apache HTTP Server 2.4, different URLs, virtual hosts, directories etc can have very different meanings to the user of the server, and thus different contexts within which modules must operate. For example, let's assume you have this configuration set up for mod_rewrite:

<Directory "/var/www">
    RewriteCond "%{HTTP_HOST}" "^example.com$"
    RewriteRule "(.*)" "http://www.example.com/$1"
</Directory>
<Directory "/var/www/sub">
    RewriteRule "^foobar$" "index.php?foobar=true"
</Directory>

In this example, you will have set up two different contexts for mod_rewrite:

  1. Inside /var/www, all requests for http://example.com must go to http://www.example.com
  2. Inside /var/www/sub, all requests for foobar must go to index.php?foobar=true

If mod_rewrite (or the entire server for that matter) wasn't context aware, then these rewrite rules would just apply to every and any request made, regardless of where and how they were made, but since the module can pull the context specific configuration straight from the server, it does not need to know itself, which of the directives are valid in this context, since the server takes care of this.

So how does a module get the specific configuration for the server, directory or location in question? It does so by making one simple call:

example_config *config = (example_config*) ap_get_module_config(r->per_dir_config, &example_module);

That's it! Of course, a whole lot goes on behind the scenes, which we will discuss in this chapter, starting with how the server came to know what our configuration looks like, and how it came to be set up as it is in the specific context.

Our basic configuration setup

In this chapter, we will be working with a slightly modified version of our previous context structure. We will set a context variable that we can use to track which context configuration is being used by the server in various places:

typedef struct {
    char        context[256];
    char        path[256];
    int         typeOfAction;
    int         enabled;
} example_config;

Our handler for requests will also be modified, yet still very simple:

static int example_handler(request_rec *r)
{
    if(!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);
    example_config *config = (example_config*) ap_get_module_config(r->per_dir_config, &example_module);
    ap_set_content_type(r, "text/plain");
    ap_rprintf("Enabled: %u\n", config->enabled);
    ap_rprintf("Path: %s\n", config->path);
    ap_rprintf("TypeOfAction: %x\n", config->typeOfAction);
    ap_rprintf("Context: %s\n", config->context);
    return OK;
}

Choosing a context

Before we can start making our module context aware, we must first define, which contexts we will accept. As we saw in the previous chapter, defining a directive required five elements be set:

AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, RSRC_CONF, "Enable or disable mod_example"),

The RSRC_CONF definition told the server that we would only allow this directive in a global server context, but since we are now trying out a context aware version of our module, we should set this to something more lenient, namely the value ACCESS_CONF, which lets us use the directive inside <Directory> and <Location> blocks. For more control over the placement of your directives, you can combine the following restrictions together to form a specific rule:

  • RSRC_CONF: Allow in .conf files (not .htaccess) outside <Directory> or <Location>
  • ACCESS_CONF: Allow in .conf files (not .htaccess) inside <Directory> or <Location>
  • OR_OPTIONS: Allow in .conf files and .htaccess when AllowOverride Options is set
  • OR_FILEINFO: Allow in .conf files and .htaccess when AllowOverride FileInfo is set
  • OR_AUTHCFG: Allow in .conf files and .htaccess when AllowOverride AuthConfig is set
  • OR_INDEXES: Allow in .conf files and .htaccess when AllowOverride Indexes is set
  • OR_ALL: Allow anywhere in .conf files and .htaccess

Using the server to allocate configuration slots

A much smarter way to manage your configurations is by letting the server help you create them. To do so, we must first start off by changing our name tag to let the server know, that it should assist us in creating and managing our configurations. Since we have chosen the per-directory (or per-location) context for our module configurations, we'll add a per-directory creator and merger function reference in our tag:

module AP_MODULE_DECLARE_DATA   example_module =
{
    STANDARD20_MODULE_STUFF,
    create_dir_conf, /* Per-directory configuration handler */
    merge_dir_conf,  /* Merge handler for per-directory configurations */
    NULL,            /* Per-server configuration handler */
    NULL,            /* Merge handler for per-server configurations */
    directives,      /* Any directives we may have for httpd */
    register_hooks   /* Our hook registering function */
};

Creating new context configurations

Now that we have told the server to help us create and manage configurations, our first step is to make a function for creating new, blank configurations. We do so by creating the function we just referenced in our name tag as the Per-directory configuration handler:

void *create_dir_conf(apr_pool_t *pool, char *context) {
    context = context ? context : "(undefined context)";
    example_config *cfg = apr_pcalloc(pool, sizeof(example_config));
    if(cfg) {
        /* Set some default values */
        strcpy(cfg->context, context);
        cfg->enabled = 0;
        cfg->path = "/foo/bar";
        cfg->typeOfAction = 0x11;
    }
    return cfg;
}

Merging configurations

Our next step in creating a context aware configuration is merging configurations. This part of the process particularly applies to scenarios where you have a parent configuration and a child, such as the following:

<Directory "/var/www">
    ExampleEnabled On
    ExamplePath "/foo/bar"
    ExampleAction file allow
</Directory>
<Directory "/var/www/subdir">
    ExampleAction file deny
</Directory>

In this example, it is natural to assume that the directory /var/www/subdir should inherit the values set for the /var/www directory, as we did not specify an ExampleEnabled nor an ExamplePath for this directory. The server does not presume to know if this is true, but cleverly does the following:

  1. Creates a new configuration for /var/www
  2. Sets the configuration values according to the directives given for /var/www
  3. Creates a new configuration for /var/www/subdir
  4. Sets the configuration values according to the directives given for /var/www/subdir
  5. Proposes a merge of the two configurations into a new configuration for /var/www/subdir

This proposal is handled by the merge_dir_conf function we referenced in our name tag. The purpose of this function is to assess the two configurations and decide how they are to be merged:

void *merge_dir_conf(apr_pool_t *pool, void *BASE, void *ADD) {
    example_config *base = (example_config *) BASE ; /* This is what was set in the parent context */
    example_config *add = (example_config *) ADD ;   /* This is what is set in the new context */
    example_config *conf = (example_config *) create_dir_conf(pool, "Merged configuration"); /* This will be the merged configuration */

    /* Merge configurations */
    conf->enabled = ( add->enabled == 0 ) ? base->enabled : add->enabled ;
    conf->typeOfAction = add->typeOfAction ? add->typeOfAction : base->typeOfAction;
    strcpy(conf->path, strlen(add->path) ? add->path : base->path);

    return conf ;
}

Trying out our new context aware configurations

Now, let's try putting it all together to create a new module that is context aware. First off, we'll create a configuration that lets us test how the module works:

<Location "/a">
    SetHandler example-handler
    ExampleEnabled on
    ExamplePath "/foo/bar"
    ExampleAction file allow
</Location>

<Location "/a/b">
    ExampleAction file deny
    ExampleEnabled off
</Location>

<Location "/a/b/c">
    ExampleAction db deny
    ExamplePath "/foo/bar/baz"
    ExampleEnabled on
</Location>

Then we'll assemble our module code. Note, that since we are now using our name tag as reference when fetching configurations in our handler, I have added some prototypes to keep the compiler happy:

/*$6
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 * mod_example_config.c
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 */

#include <stdio.h>
#include "apr_hash.h"
#include "ap_config.h"
#include "ap_provider.h"
#include "httpd.h"
#include "http_core.h"
#include "http_config.h"
#include "http_log.h"
#include "http_protocol.h"
#include "http_request.h"

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Configuration structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

typedef struct
{
    char    context[256];
    char    path[256];
    int     typeOfAction;
    int     enabled;
} example_config;

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Prototypes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

static int    example_handler(request_rec *r);
const char    *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg);
const char    *example_set_path(cmd_parms *cmd, void *cfg, const char *arg);
const char    *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2);
void          *create_dir_conf(apr_pool_t *pool, char *context);
void          *merge_dir_conf(apr_pool_t *pool, void *BASE, void *ADD);
static void   register_hooks(apr_pool_t *pool);

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Configuration directives
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

static const command_rec    directives[] =
{
    AP_INIT_TAKE1("exampleEnabled", example_set_enabled, NULL, ACCESS_CONF, "Enable or disable mod_example"),
    AP_INIT_TAKE1("examplePath", example_set_path, NULL, ACCESS_CONF, "The path to whatever"),
    AP_INIT_TAKE2("exampleAction", example_set_action, NULL, ACCESS_CONF, "Special action value!"),
    { NULL }
};

/*$1
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Our name tag
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */

module AP_MODULE_DECLARE_DATA    example_module =
{
    STANDARD20_MODULE_STUFF,
    create_dir_conf,    /* Per-directory configuration handler */
    merge_dir_conf,     /* Merge handler for per-directory configurations */
    NULL,               /* Per-server configuration handler */
    NULL,               /* Merge handler for per-server configurations */
    directives,         /* Any directives we may have for httpd */
    register_hooks      /* Our hook registering function */
};

/*
 =======================================================================================================================
    Hook registration function
 =======================================================================================================================
 */
static void register_hooks(apr_pool_t *pool)
{
    ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST);
}

/*
 =======================================================================================================================
    Our example web service handler
 =======================================================================================================================
 */
static int example_handler(request_rec *r)
{
    if(!r->handler || strcmp(r->handler, "example-handler")) return(DECLINED);

    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *config = (example_config *) ap_get_module_config(r->per_dir_config, &example_module);
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    ap_set_content_type(r, "text/plain");
    ap_rprintf(r, "Enabled: %u\n", config->enabled);
    ap_rprintf(r, "Path: %s\n", config->path);
    ap_rprintf(r, "TypeOfAction: %x\n", config->typeOfAction);
    ap_rprintf(r, "Context: %s\n", config->context);
    return OK;
}

/*
 =======================================================================================================================
    Handler for the "exampleEnabled" directive
 =======================================================================================================================
 */
const char *example_set_enabled(cmd_parms *cmd, void *cfg, const char *arg)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *conf = (example_config *) cfg;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(conf)
    {
        if(!strcasecmp(arg, "on"))
            conf->enabled = 1;
        else
            conf->enabled = 0;
    }

    return NULL;
}

/*
 =======================================================================================================================
    Handler for the "examplePath" directive
 =======================================================================================================================
 */
const char *example_set_path(cmd_parms *cmd, void *cfg, const char *arg)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *conf = (example_config *) cfg;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(conf)
    {
        strcpy(conf->path, arg);
    }

    return NULL;
}

/*
 =======================================================================================================================
    Handler for the "exampleAction" directive ;
    Let's pretend this one takes one argument (file or db), and a second (deny or allow), ;
    and we store it in a bit-wise manner.
 =======================================================================================================================
 */
const char *example_set_action(cmd_parms *cmd, void *cfg, const char *arg1, const char *arg2)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *conf = (example_config *) cfg;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(conf)
    {
        {
            if(!strcasecmp(arg1, "file"))
                conf->typeOfAction = 0x01;
            else
                conf->typeOfAction = 0x02;
            if(!strcasecmp(arg2, "deny"))
                conf->typeOfAction += 0x10;
            else
                conf->typeOfAction += 0x20;
        }
    }

    return NULL;
}

/*
 =======================================================================================================================
    Function for creating new configurations for per-directory contexts
 =======================================================================================================================
 */
void *create_dir_conf(apr_pool_t *pool, char *context)
{
    context = context ? context : "Newly created configuration";

    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *cfg = apr_pcalloc(pool, sizeof(example_config));
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    if(cfg)
    {
        {
            /* Set some default values */
            strcpy(cfg->context, context);
            cfg->enabled = 0;
            memset(cfg->path, 0, 256);
            cfg->typeOfAction = 0x00;
        }
    }

    return cfg;
}

/*
 =======================================================================================================================
    Merging function for configurations
 =======================================================================================================================
 */
void *merge_dir_conf(apr_pool_t *pool, void *BASE, void *ADD)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    example_config    *base = (example_config *) BASE;
    example_config    *add = (example_config *) ADD;
    example_config    *conf = (example_config *) create_dir_conf(pool, "Merged configuration");
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    conf->enabled = (add->enabled == 0) ? base->enabled : add->enabled;
    conf->typeOfAction = add->typeOfAction ? add->typeOfAction : base->typeOfAction;
    strcpy(conf->path, strlen(add->path) ? add->path : base->path);
    return conf;
}

Summing up

We have now looked at how to create simple modules for Apache HTTP Server 2.4 and configuring them. What you do next is entirely up to you, but it is my hope that something valuable has come out of reading this documentation. If you have questions on how to further develop modules, you are welcome to join our mailing lists or check out the rest of our documentation for further tips.

Some useful snippets of code

Retrieve variables from POST form data

typedef struct {
    const char *key;
    const char *value;
} keyValuePair;

keyValuePair *readPost(request_rec *r) {
    apr_array_header_t *pairs = NULL;
    apr_off_t len;
    apr_size_t size;
    int res;
    int i = 0;
    char *buffer;
    keyValuePair *kvp;

    res = ap_parse_form_data(r, NULL, &pairs, -1, HUGE_STRING_LEN);
    if (res != OK || !pairs) return NULL; /* Return NULL if we failed or if there are is no POST data */
    kvp = apr_pcalloc(r->pool, sizeof(keyValuePair) * (pairs->nelts + 1));
    while (pairs && !apr_is_empty_array(pairs)) {
        ap_form_pair_t *pair = (ap_form_pair_t *) apr_array_pop(pairs);
        apr_brigade_length(pair->value, 1, &len);
        size = (apr_size_t) len;
        buffer = apr_palloc(r->pool, size + 1);
        apr_brigade_flatten(pair->value, buffer, &size);
        buffer[len] = 0;
        kvp[i].key = apr_pstrdup(r->pool, pair->name);
        kvp[i].value = buffer;
        i++;
    }
    return kvp;
}

static int example_handler(request_rec *r)
{
    /*~~~~~~~~~~~~~~~~~~~~~~*/
    keyValuePair *formData;
    /*~~~~~~~~~~~~~~~~~~~~~~*/

    formData = readPost(r);
    if (formData) {
        int i;
        for (i = 0; &formData[i]; i++) {
            if (formData[i].key && formData[i].value) {
                ap_rprintf(r, "%s = %s\n", formData[i].key, formData[i].value);
            } else if (formData[i].key) {
                ap_rprintf(r, "%s\n", formData[i].key);
            } else if (formData[i].value) {
                ap_rprintf(r, "= %s\n", formData[i].value);
            } else {
                break;
            }
        }
    }
    return OK;
}

Printing out every HTTP header received

static int example_handler(request_rec *r)
{
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
    const apr_array_header_t    *fields;
    int                         i;
    apr_table_entry_t           *e = 0;
    /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

    fields = apr_table_elts(r->headers_in);
    e = (apr_table_entry_t *) fields->elts;
    for(i = 0; i < fields->nelts; i++) {
        ap_rprintf(r, "%s: %s\n", e[i].key, e[i].val);
    }
    return OK;
}

Reading the request body into memory

static int util_read(request_rec *r, const char **rbuf, apr_off_t *size)
{
    /*~~~~~~~~*/
    int rc = OK;
    /*~~~~~~~~*/

    if((rc = ap_setup_client_block(r, REQUEST_CHUNKED_ERROR))) {
        return(rc);
    }

    if(ap_should_client_block(r)) {

        /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
        char         argsbuffer[HUGE_STRING_LEN];
        apr_off_t    rsize, len_read, rpos = 0;
        apr_off_t length = r->remaining;
        /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

        *rbuf = (const char *) apr_pcalloc(r->pool, (apr_size_t) (length + 1));
        *size = length;
        while((len_read = ap_get_client_block(r, argsbuffer, sizeof(argsbuffer))) > 0) {
            if((rpos + len_read) > length) {
                rsize = length - rpos;
            }
            else {
                rsize = len_read;
            }

            memcpy((char *) *rbuf + rpos, argsbuffer, (size_t) rsize);
            rpos += rsize;
        }
    }
    return(rc);
}

static int example_handler(request_rec *r)
{
    /*~~~~~~~~~~~~~~~~*/
    apr_off_t   size;
    const char  *buffer;
    /*~~~~~~~~~~~~~~~~*/

    if(util_read(r, &buffer, &size) == OK) {
        ap_rprintf(r, "We read a request body that was %" APR_OFF_T_FMT " bytes long", size);
    }
    return OK;
}

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Documenting code in Apache 2.4 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Documenting code in Apache 2.4

Apache 2.4 uses Doxygen to document the APIs and global variables in the code. This will explain the basics of how to document using Doxygen.

Brief Description

To start a documentation block, use /**
To end a documentation block, use */

In the middle of the block, there are multiple tags we can use:

Description of this functions purpose
@param parameter_name description
@return description
@deffunc signature of the function

The deffunc is not always necessary. DoxyGen does not have a full parser in it, so any prototype that use a macro in the return type declaration is too complex for scandoc. Those functions require a deffunc. An example (using &gt; rather than >):

/**
 * return the final element of the pathname
 * @param pathname The path to get the final element of
 * @return the final element of the path
 * @tip Examples:
 * <pre>
 * "/foo/bar/gum" -&gt; "gum"
 * "/foo/bar/gum/" -&gt; ""
 * "gum" -&gt; "gum"
 * "wi\\n32\\stuff" -&gt; "stuff"
 * </pre>
 * @deffunc const char * ap_filename_of_pathname(const char *pathname)
 */

At the top of the header file, always include:

/**
 * @package Name of library header
 */

Doxygen uses a new HTML file for each package. The HTML files are named {Name_of_library_header}.html, so try to be concise with your names.

For a further discussion of the possibilities please refer to the Doxygen site.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Hook Functions in the Apache HTTP Server 2.x - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Hook Functions in the Apache HTTP Server 2.x

Warning

This document is still in development and may be partially out of date.

In general, a hook function is one that the Apache HTTP Server will call at some point during the processing of a request. Modules can provide functions that are called, and specify when they get called in comparison to other modules.

Core Hooks

The httpd's core modules offer a predefinined list of hooks used during the standard request processing phase. Creating a new hook will expose a function that implements it (see sections below) but it is essential to undestand that you will not extend the httpd's core hooks. Their presence and order in the request processing is in fact a consequence of how they are called in server/request.c (check this section for an overview). The core hooks are listed in the doxygen documentation.

Reading guide for developing modules and request processing before proceeding is highly recomended.

Creating a hook function

In order to create a new hook, four things need to be done:

Declare the hook function

Use the AP_DECLARE_HOOK macro, which needs to be given the return type of the hook function, the name of the hook, and the arguments. For example, if the hook returns an int and takes a request_rec * and an int and is called do_something, then declare it like this:

AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))

This should go in a header which modules will include if they want to use the hook.

Create the hook structure

Each source file that exports a hook has a private structure which is used to record the module functions that use the hook. This is declared as follows:

APR_HOOK_STRUCT(
  APR_HOOK_LINK(do_something)
  ...
)

Implement the hook caller

The source file that exports the hook has to implement a function that will call the hook. There are currently three possible ways to do this. In all cases, the calling function is called ap_run_hookname().

Void hooks

If the return value of a hook is void, then all the hooks are called, and the caller is implemented like this:

AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))

The second and third arguments are the dummy argument declaration and the dummy arguments as they will be used when calling the hook. In other words, this macro expands to something like this:

void ap_run_do_something(request_rec *r, int n)
{
    ...
    do_something(r, n);
}

Hooks that return a value

If the hook returns a value, then it can either be run until the first hook that does something interesting, like so:

AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED)

The first hook that does not return DECLINED stops the loop and its return value is returned from the hook caller. Note that DECLINED is the traditional hook return value meaning "I didn't do anything", but it can be whatever suits you.

Alternatively, all hooks can be run until an error occurs. This boils down to permitting two return values, one of which means "I did something, and it was OK" and the other meaning "I did nothing". The first function that returns a value other than one of those two stops the loop, and its return is the return value. Declare these like so:

AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED)

Again, OK and DECLINED are the traditional values. You can use what you want.

Call the hook callers

At appropriate moments in the code, call the hook caller, like so:

int n, ret;
request_rec *r;

ret=ap_run_do_something(r, n);

Hooking the hook

A module that wants a hook to be called needs to do two things.

Implement the hook function

Include the appropriate header, and define a static function of the correct type:

static int my_something_doer(request_rec *r, int n)
{
    ...
    return OK;
}

Add a hook registering function

During initialisation, the server will call each modules hook registering function, which is included in the module structure:

static void my_register_hooks()
{
    ap_hook_do_something(my_something_doer, NULL, NULL, APR_HOOK_MIDDLE);
}

mode MODULE_VAR_EXPORT my_module =
{
    ...
    my_register_hooks       /* register hooks */
};

Controlling hook calling order

In the example above, we didn't use the three arguments in the hook registration function that control calling order of all the functions registered within the hook. There are two mechanisms for doing this. The first, rather crude, method, allows us to specify roughly where the hook is run relative to other modules. The final argument control this. There are three possible values: APR_HOOK_FIRST, APR_HOOK_MIDDLE and APR_HOOK_LAST.

All modules using any particular value may be run in any order relative to each other, but, of course, all modules using APR_HOOK_FIRST will be run before APR_HOOK_MIDDLE which are before APR_HOOK_LAST. Modules that don't care when they are run should use APR_HOOK_MIDDLE. These values are spaced out, so that positions like APR_HOOK_FIRST-2 are possible to hook slightly earlier than other functions.

Note that there are two more values, APR_HOOK_REALLY_FIRST and APR_HOOK_REALLY_LAST. These should only be used by the hook exporter.

The other method allows finer control. When a module knows that it must be run before (or after) some other modules, it can specify them by name. The second (third) argument is a NULL-terminated array of strings consisting of the names of modules that must be run before (after) the current module. For example, suppose we want "mod_xyz.c" and "mod_abc.c" to run before we do, then we'd hook as follows:

static void register_hooks()
{
    static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };

    ap_hook_do_something(my_something_doer, aszPre, NULL, APR_HOOK_MIDDLE);
}

Note that the sort used to achieve this is stable, so ordering set by APR_HOOK_ORDER is preserved, as far as is possible.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Converting Modules from Apache 1.3 to Apache 2.0 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Converting Modules from Apache 1.3 to Apache 2.0

This is a first attempt at writing the lessons I learned when trying to convert the mod_mmap_static module to Apache 2.0. It's by no means definitive and probably won't even be correct in some ways, but it's a start.

The easier changes ...

Cleanup Routines

These now need to be of type apr_status_t and return a value of that type. Normally the return value will be APR_SUCCESS unless there is some need to signal an error in the cleanup. Be aware that even though you signal an error not all code yet checks and acts upon the error.

Initialisation Routines

These should now be renamed to better signify where they sit in the overall process. So the name gets a small change from mmap_init to mmap_post_config. The arguments passed have undergone a radical change and now look like

  • apr_pool_t *p
  • apr_pool_t *plog
  • apr_pool_t *ptemp
  • server_rec *s

Data Types

A lot of the data types have been moved into the APR. This means that some have had a name change, such as the one shown above. The following is a brief list of some of the changes that you are likely to have to make.

  • pool becomes apr_pool_t
  • table becomes apr_table_t

The messier changes...

Register Hooks

The new architecture uses a series of hooks to provide for calling your functions. These you'll need to add to your module by way of a new function, static void register_hooks(void). The function is really reasonably straightforward once you understand what needs to be done. Each function that needs calling at some stage in the processing of a request needs to be registered, handlers do not. There are a number of phases where functions can be added, and for each you can specify with a high degree of control the relative order that the function will be called in.

This is the code that was added to mod_mmap_static:

static void register_hooks(void)
{
    static const char * const aszPre[]={ "http_core.c",NULL };
    ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
    ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
};

This registers 2 functions that need to be called, one in the post_config stage (virtually every module will need this one) and one for the translate_name phase. note that while there are different function names the format of each is identical. So what is the format?

ap_hook_phase_name(function_name, predecessors, successors, position);

There are 3 hook positions defined...

  • HOOK_FIRST
  • HOOK_MIDDLE
  • HOOK_LAST

To define the position you use the position and then modify it with the predecessors and successors. Each of the modifiers can be a list of functions that should be called, either before the function is run (predecessors) or after the function has run (successors).

In the mod_mmap_static case I didn't care about the post_config stage, but the mmap_static_xlat must be called after the core module had done its name translation, hence the use of the aszPre to define a modifier to the position HOOK_LAST.

Module Definition

There are now a lot fewer stages to worry about when creating your module definition. The old definition looked like

module MODULE_VAR_EXPORT module_name_module =
{
    STANDARD_MODULE_STUFF,
    /* initializer */
    /* dir config creater */
    /* dir merger --- default is to override */
    /* server config */
    /* merge server config */
    /* command handlers */
    /* handlers */
    /* filename translation */
    /* check_user_id */
    /* check auth */
    /* check access */
    /* type_checker */
    /* fixups */
    /* logger */
    /* header parser */
    /* child_init */
    /* child_exit */
    /* post read-request */
};

The new structure is a great deal simpler...

module MODULE_VAR_EXPORT module_name_module =
{
    STANDARD20_MODULE_STUFF,
    /* create per-directory config structures */
    /* merge per-directory config structures  */
    /* create per-server config structures    */
    /* merge per-server config structures     */
    /* command handlers */
    /* handlers */
    /* register hooks */
};

Some of these read directly across, some don't. I'll try to summarise what should be done below.

The stages that read directly across :

/* dir config creater */
/* create per-directory config structures */
/* server config */
/* create per-server config structures */
/* dir merger */
/* merge per-directory config structures */
/* merge server config */
/* merge per-server config structures */
/* command table */
/* command apr_table_t */
/* handlers */
/* handlers */

The remainder of the old functions should be registered as hooks. There are the following hook stages defined so far...

ap_hook_pre_config
do any setup required prior to processing configuration directives
ap_hook_check_config
review configuration directive interdependencies
ap_hook_test_config
executes only with -t option
ap_hook_open_logs
open any specified logs
ap_hook_post_config
this is where the old _init routines get registered
ap_hook_http_method
retrieve the http method from a request. (legacy)
ap_hook_auth_checker
check if the resource requires authorization
ap_hook_access_checker
check for module-specific restrictions
ap_hook_check_user_id
check the user-id and password
ap_hook_default_port
retrieve the default port for the server
ap_hook_pre_connection
do any setup required just before processing, but after accepting
ap_hook_process_connection
run the correct protocol
ap_hook_child_init
call as soon as the child is started
ap_hook_create_request
??
ap_hook_fixups
last chance to modify things before generating content
ap_hook_handler
generate the content
ap_hook_header_parser
lets modules look at the headers, not used by most modules, because they use post_read_request for this
ap_hook_insert_filter
to insert filters into the filter chain
ap_hook_log_transaction
log information about the request
ap_hook_optional_fn_retrieve
retrieve any functions registered as optional
ap_hook_post_read_request
called after reading the request, before any other phase
ap_hook_quick_handler
called before any request processing, used by cache modules.
ap_hook_translate_name
translate the URI into a filename
ap_hook_type_checker
determine and/or set the doc type

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Request Processing in the Apache HTTP Server 2.x - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Request Processing in the Apache HTTP Server 2.x

Warning

Warning - this is a first (fast) draft that needs further revision!

Several changes in 2.0 and above affect the internal request processing mechanics. Module authors need to be aware of these changes so they may take advantage of the optimizations and security enhancements.

The first major change is to the subrequest and redirect mechanisms. There were a number of different code paths in the Apache HTTP Server 1.3 to attempt to optimize subrequest or redirect behavior. As patches were introduced to 2.0, these optimizations (and the server behavior) were quickly broken due to this duplication of code. All duplicate code has been folded back into ap_process_request_internal() to prevent the code from falling out of sync again.

This means that much of the existing code was 'unoptimized'. It is the Apache HTTP Project's first goal to create a robust and correct implementation of the HTTP server RFC. Additional goals include security, scalability and optimization. New methods were sought to optimize the server (beyond the performance of 1.3) without introducing fragile or insecure code.

The Request Processing Cycle

All requests pass through ap_process_request_internal() in server/request.c, including subrequests and redirects. If a module doesn't pass generated requests through this code, the author is cautioned that the module may be broken by future changes to request processing.

To streamline requests, the module author can take advantage of the hooks offered to drop out of the request cycle early, or to bypass core hooks which are irrelevant (and costly in terms of CPU.)

The Request Parsing Phase

Unescapes the URL

The request's parsed_uri path is unescaped, once and only once, at the beginning of internal request processing.

This step is bypassed if the proxyreq flag is set, or the parsed_uri.path element is unset. The module has no further control of this one-time unescape operation, either failing to unescape or multiply unescaping the URL leads to security repercussions.

Strips Parent and This Elements from the URI

All /../ and /./ elements are removed by ap_getparents(). This helps to ensure the path is (nearly) absolute before the request processing continues.

This step cannot be bypassed.

Initial URI Location Walk

Every request is subject to an ap_location_walk() call. This ensures that <Location> sections are consistently enforced for all requests. If the request is an internal redirect or a sub-request, it may borrow some or all of the processing from the previous or parent request's ap_location_walk, so this step is generally very efficient after processing the main request.

translate_name

Modules can determine the file name, or alter the given URI in this step. For example, mod_vhost_alias will translate the URI's path into the configured virtual host, mod_alias will translate the path to an alias path, and if the request falls back on the core, the DocumentRoot is prepended to the request resource.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't translate name" error is logged automatically.

Hook: map_to_storage

After the file or correct URI was determined, the appropriate per-dir configurations are merged together. For example, mod_proxy compares and merges the appropriate <Proxy> sections. If the URI is nothing more than a local (non-proxy) TRACE request, the core handles the request and returns DONE. If no module answers this hook with OK or DONE, the core will run the request filename against the <Directory> and <Files> sections. If the request 'filename' isn't an absolute, legal filename, a note is set for later termination.

URI Location Walk

Every request is hardened by a second ap_location_walk() call. This reassures that a translated request is still subjected to the configured <Location> sections. The request again borrows some or all of the processing from its previous location_walk above, so this step is almost always very efficient unless the translated URI mapped to a substantially different path or Virtual Host.

Hook: header_parser

The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.

The Security Phase

Needs Documentation. Code is:

if ((access_status = ap_run_access_checker(r)) != 0) {
    return decl_die(access_status, "check access", r);
}

if ((access_status = ap_run_check_user_id(r)) != 0) {
    return decl_die(access_status, "check user", r);
}

if ((access_status = ap_run_auth_checker(r)) != 0) {
    return decl_die(access_status, "check authorization", r);
}

The Preparation Phase

Hook: type_checker

The modules have an opportunity to test the URI or filename against the target resource, and set mime information for the request. Both mod_mime and mod_mime_magic use this phase to compare the file name or contents against the administrator's configuration and set the content type, language, character set and request handler. Some modules may set up their filters or other request handling parameters at this time.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't find types" error is logged automatically.

Hook: fixups

Many modules are 'trounced' by some phase above. The fixups phase is used by modules to 'reassert' their ownership or force the request's fields to their appropriate values. It isn't always the cleanest mechanism, but occasionally it's the only option.

The Handler Phase

This phase is not part of the processing in ap_process_request_internal(). Many modules prepare one or more subrequests prior to creating any content at all. After the core, or a module calls ap_process_request_internal() it then calls ap_invoke_handler() to generate the request.

Hook: insert_filter

Modules that transform the content in some way can insert their values and override existing filters, such that if the user configured a more advanced filter out-of-order, then the module can move its order as need be. There is no result code, so actions in this hook better be trusted to always succeed.

Hook: handler

The module finally has a chance to serve the request in its handler hook. Note that not every prepared request is sent to the handler hook. Many modules, such as mod_autoindex, will create subrequests for a given URI, and then never serve the subrequest, but simply lists it for the user. Remember not to put required teardown from the hooks above into this module, but register pool cleanups against the request pool to free resources as required.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


How filters work in Apache 2.0 - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

How filters work in Apache 2.0

Warning

This is a cut 'n paste job from an email (<022501c1c529$f63a9550$7f00000a@KOJ>) and only reformatted for better readability. It's not up to date but may be a good start for further research.

Filter Types

There are three basic filter types (each of these is actually broken down into two categories, but that comes later).

CONNECTION
Filters of this type are valid for the lifetime of this connection. (AP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)
PROTOCOL
Filters of this type are valid for the lifetime of this request from the point of view of the client, this means that the request is valid from the time that the request is sent until the time that the response is received. (AP_FTYPE_PROTOCOL, AP_FTYPE_TRANSCODE)
RESOURCE
Filters of this type are valid for the time that this content is used to satisfy a request. For simple requests, this is identical to PROTOCOL, but internal redirects and sub-requests can change the content without ending the request. (AP_FTYPE_RESOURCE, AP_FTYPE_CONTENT_SET)

It is important to make the distinction between a protocol and a resource filter. A resource filter is tied to a specific resource, it may also be tied to header information, but the main binding is to a resource. If you are writing a filter and you want to know if it is resource or protocol, the correct question to ask is: "Can this filter be removed if the request is redirected to a different resource?" If the answer is yes, then it is a resource filter. If it is no, then it is most likely a protocol or connection filter. I won't go into connection filters, because they seem to be well understood. With this definition, a few examples might help:

Byterange
We have coded it to be inserted for all requests, and it is removed if not used. Because this filter is active at the beginning of all requests, it can not be removed if it is redirected, so this is a protocol filter.
http_header
This filter actually writes the headers to the network. This is obviously a required filter (except in the asis case which is special and will be dealt with below) and so it is a protocol filter.
Deflate
The administrator configures this filter based on which file has been requested. If we do an internal redirect from an autoindex page to an index.html page, the deflate filter may be added or removed based on config, so this is a resource filter.

The further breakdown of each category into two more filter types is strictly for ordering. We could remove it, and only allow for one filter type, but the order would tend to be wrong, and we would need to hack things to make it work. Currently, the RESOURCE filters only have one filter type, but that should change.

How are filters inserted?

This is actually rather simple in theory, but the code is complex. First of all, it is important that everybody realize that there are three filter lists for each request, but they are all concatenated together:

  • r->output_filters (corresponds to RESOURCE)
  • r->proto_output_filters (corresponds to PROTOCOL)
  • r->connection->output_filters (corresponds to CONNECTION)

The problem previously, was that we used a singly linked list to create the filter stack, and we started from the "correct" location. This means that if I had a RESOURCE filter on the stack, and I added a CONNECTION filter, the CONNECTION filter would be ignored. This should make sense, because we would insert the connection filter at the top of the c->output_filters list, but the end of r->output_filters pointed to the filter that used to be at the front of c->output_filters. This is obviously wrong. The new insertion code uses a doubly linked list. This has the advantage that we never lose a filter that has been inserted. Unfortunately, it comes with a separate set of headaches.

The problem is that we have two different cases were we use subrequests. The first is to insert more data into a response. The second is to replace the existing response with an internal redirect. These are two different cases and need to be treated as such.

In the first case, we are creating the subrequest from within a handler or filter. This means that the next filter should be passed to make_sub_request function, and the last resource filter in the sub-request will point to the next filter in the main request. This makes sense, because the sub-request's data needs to flow through the same set of filters as the main request. A graphical representation might help:

Default_handler --> includes_filter --> byterange --> ...

If the includes filter creates a sub request, then we don't want the data from that sub-request to go through the includes filter, because it might not be SSI data. So, the subrequest adds the following:

Default_handler --> includes_filter -/-> byterange --> ...
                                    /
Default_handler --> sub_request_core

What happens if the subrequest is SSI data? Well, that's easy, the includes_filter is a resource filter, so it will be added to the sub request in between the Default_handler and the sub_request_core filter.

The second case for sub-requests is when one sub-request is going to become the real request. This happens whenever a sub-request is created outside of a handler or filter, and NULL is passed as the next filter to the make_sub_request function.

In this case, the resource filters no longer make sense for the new request, because the resource has changed. So, instead of starting from scratch, we simply point the front of the resource filters for the sub-request to the front of the protocol filters for the old request. This means that we won't lose any of the protocol filters, neither will we try to send this data through a filter that shouldn't see it.

The problem is that we are using a doubly-linked list for our filter stacks now. But, you should notice that it is possible for two lists to intersect in this model. So, you do you handle the previous pointer? This is a very difficult question to answer, because there is no "right" answer, either method is equally valid. I looked at why we use the previous pointer. The only reason for it is to allow for easier addition of new servers. With that being said, the solution I chose was to make the previous pointer always stay on the original request.

This causes some more complex logic, but it works for all cases. My concern in having it move to the sub-request, is that for the more common case (where a sub-request is used to add data to a response), the main filter chain would be wrong. That didn't seem like a good idea to me.

Asis

The final topic. :-) Mod_Asis is a bit of a hack, but the handler needs to remove all filters except for connection filters, and send the data. If you are using mod_asis, all other bets are off.

Explanations

The absolutely last point is that the reason this code was so hard to get right, was because we had hacked so much to force it to work. I wrote most of the hacks originally, so I am very much to blame. However, now that the code is right, I have started to remove some hacks. Most people should have seen that the reset_filters and add_required_filters functions are gone. Those inserted protocol level filters for error conditions, in fact, both functions did the same thing, one after the other, it was really strange. Because we don't lose protocol filters for error cases any more, those hacks went away. The HTTP_HEADER, Content-length, and Byterange filters are all added in the insert_filters phase, because if they were added earlier, we had some interesting interactions. Now, those could all be moved to be inserted with the HTTP_IN, CORE, and CORE_IN filters. That would make the code easier to follow.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Guide to writing output filters - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Guide to writing output filters

There are a number of common pitfalls encountered when writing output filters; this page aims to document best practice for authors of new or existing filters.

This document is applicable to both version 2.0 and version 2.2 of the Apache HTTP Server; it specifically targets RESOURCE-level or CONTENT_SET-level filters though some advice is generic to all types of filter.

Filters and bucket brigades

Each time a filter is invoked, it is passed a bucket brigade, containing a sequence of buckets which represent both data content and metadata. Every bucket has a bucket type; a number of bucket types are defined and used by the httpd core modules (and the apr-util library which provides the bucket brigade interface), but modules are free to define their own types.

Output filters must be prepared to process buckets of non-standard types; with a few exceptions, a filter need not care about the types of buckets being filtered.

A filter can tell whether a bucket represents either data or metadata using the APR_BUCKET_IS_METADATA macro. Generally, all metadata buckets should be passed down the filter chain by an output filter. Filters may transform, delete, and insert data buckets as appropriate.

There are two metadata bucket types which all filters must pay attention to: the EOS bucket type, and the FLUSH bucket type. An EOS bucket indicates that the end of the response has been reached and no further buckets need be processed. A FLUSH bucket indicates that the filter should flush any buffered buckets (if applicable) down the filter chain immediately.

FLUSH buckets are sent when the content generator (or an upstream filter) knows that there may be a delay before more content can be sent. By passing FLUSH buckets down the filter chain immediately, filters ensure that the client is not kept waiting for pending data longer than necessary.

Filters can create FLUSH buckets and pass these down the filter chain if desired. Generating FLUSH buckets unnecessarily, or too frequently, can harm network utilisation since it may force large numbers of small packets to be sent, rather than a small number of larger packets. The section on Non-blocking bucket reads covers a case where filters are encouraged to generate FLUSH buckets.

Example bucket brigade

HEAP FLUSH FILE EOS

This shows a bucket brigade which may be passed to a filter; it contains two metadata buckets (FLUSH and EOS), and two data buckets (HEAP and FILE).

Filter invocation

For any given request, an output filter might be invoked only once and be given a single brigade representing the entire response. It is also possible that the number of times a filter is invoked for a single response is proportional to the size of the content being filtered, with the filter being passed a brigade containing a single bucket each time. Filters must operate correctly in either case.

An output filter which allocates long-lived memory every time it is invoked may consume memory proportional to response size. Output filters which need to allocate memory should do so once per response; see Maintaining state below.

An output filter can distinguish the final invocation for a given response by the presence of an EOS bucket in the brigade. Any buckets in the brigade after an EOS should be ignored.

An output filter should never pass an empty brigade down the filter chain. To be defensive, filters should be prepared to accept an empty brigade, and should return success without passing this brigade on down the filter chain. The handling of an empty brigade should have no side effects (such as changing any state private to the filter).

How to handle an empty brigade

apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
{
    if (APR_BRIGADE_EMPTY(bb)) {
        return APR_SUCCESS;
    }
    ...

Brigade structure

A bucket brigade is a doubly-linked list of buckets. The list is terminated (at both ends) by a sentinel which can be distinguished from a normal bucket by comparing it with the pointer returned by APR_BRIGADE_SENTINEL. The list sentinel is in fact not a valid bucket structure; any attempt to call normal bucket functions (such as apr_bucket_read) on the sentinel will have undefined behaviour (i.e. will crash the process).

There are a variety of functions and macros for traversing and manipulating bucket brigades; see the apr_buckets.h header for complete coverage. Commonly used macros include:

APR_BRIGADE_FIRST(bb)
returns the first bucket in brigade bb
APR_BRIGADE_LAST(bb)
returns the last bucket in brigade bb
APR_BUCKET_NEXT(e)
gives the next bucket after bucket e
APR_BUCKET_PREV(e)
gives the bucket before bucket e

The apr_bucket_brigade structure itself is allocated out of a pool, so if a filter creates a new brigade, it must ensure that memory use is correctly bounded. A filter which allocates a new brigade out of the request pool (r->pool) on every invocation, for example, will fall foul of the warning above concerning memory use. Such a filter should instead create a brigade on the first invocation per request, and store that brigade in its state structure.

It is generally never advisable to use apr_brigade_destroy to "destroy" a brigade unless you know for certain that the brigade will never be used again, even then, it should be used rarely. The memory used by the brigade structure will not be released by calling this function (since it comes from a pool), but the associated pool cleanup is unregistered. Using apr_brigade_destroy can in fact cause memory leaks; if a "destroyed" brigade contains buckets when its containing pool is destroyed, those buckets will not be immediately destroyed.

In general, filters should use apr_brigade_cleanup in preference to apr_brigade_destroy.

Processing buckets

When dealing with non-metadata buckets, it is important to understand that the "apr_bucket *" object is an abstract representation of data:

  1. The amount of data represented by the bucket may or may not have a determinate length; for a bucket which represents data of indeterminate length, the ->length field is set to the value (apr_size_t)-1. For example, buckets of the PIPE bucket type have an indeterminate length; they represent the output from a pipe.
  2. The data represented by a bucket may or may not be mapped into memory. The FILE bucket type, for example, represents data stored in a file on disk.

Filters read the data from a bucket using the apr_bucket_read function. When this function is invoked, the bucket may morph into a different bucket type, and may also insert a new bucket into the bucket brigade. This must happen for buckets which represent data not mapped into memory.

To give an example; consider a bucket brigade containing a single FILE bucket representing an entire file, 24 kilobytes in size:

FILE(0K-24K)

When this bucket is read, it will read a block of data from the file, morph into a HEAP bucket to represent that data, and return the data to the caller. It also inserts a new FILE bucket representing the remainder of the file; after the apr_bucket_read call, the brigade looks like:

HEAP(8K) FILE(8K-24K)

Filtering brigades

The basic function of any output filter will be to iterate through the passed-in brigade and transform (or simply examine) the content in some manner. The implementation of the iteration loop is critical to producing a well-behaved output filter.

Taking an example which loops through the entire brigade as follows:

Bad output filter -- do not imitate!

apr_bucket *e = APR_BRIGADE_FIRST(bb);
const char *data;
apr_size_t length;

while (e != APR_BRIGADE_SENTINEL(bb)) {
    apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
    e = APR_BUCKET_NEXT(e);
}

return ap_pass_brigade(bb);

The above implementation would consume memory proportional to content size. If passed a FILE bucket, for example, the entire file contents would be read into memory as each apr_bucket_read call morphed a FILE bucket into a HEAP bucket.

In contrast, the implementation below will consume a fixed amount of memory to filter any brigade; a temporary brigade is needed and must be allocated only once per response, see the Maintaining state section.

Better output filter

apr_bucket *e;
const char *data;
apr_size_t length;

while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
    rv = apr_bucket_read(e, &data, &length, APR_BLOCK_READ);
    if (rv) ...;
    /* Remove bucket e from bb. */
    APR_BUCKET_REMOVE(e);
    /* Insert it into  temporary brigade. */
    APR_BRIGADE_INSERT_HEAD(tmpbb, e);
    /* Pass brigade downstream. */
    rv = ap_pass_brigade(f->next, tmpbb);
    if (rv) ...;
    apr_brigade_cleanup(tmpbb);
}

Maintaining state

A filter which needs to maintain state over multiple invocations per response can use the ->ctx field of its ap_filter_t structure. It is typical to store a temporary brigade in such a structure, to avoid having to allocate a new brigade per invocation as described in the Brigade structure section.

Example code to maintain filter state

struct dummy_state {
    apr_bucket_brigade *tmpbb;
    int filter_state;
    ...
};

apr_status_t dummy_filter(ap_filter_t *f, apr_bucket_brigade *bb)
{
    struct dummy_state *state;

    state = f->ctx;
    if (state == NULL) {

        /* First invocation for this response: initialise state structure.
         */
        f->ctx = state = apr_palloc(f->r->pool, sizeof *state);

        state->tmpbb = apr_brigade_create(f->r->pool, f->c->bucket_alloc);
        state->filter_state = ...;
    }
    ...

Buffering buckets

If a filter decides to store buckets beyond the duration of a single filter function invocation (for example storing them in its ->ctx state structure), those buckets must be set aside. This is necessary because some bucket types provide buckets which represent temporary resources (such as stack memory) which will fall out of scope as soon as the filter chain completes processing the brigade.

To setaside a bucket, the apr_bucket_setaside function can be called. Not all bucket types can be setaside, but if successful, the bucket will have morphed to ensure it has a lifetime at least as long as the pool given as an argument to the apr_bucket_setaside function.

Alternatively, the ap_save_brigade function can be used, which will move all the buckets into a separate brigade containing buckets with a lifetime as long as the given pool argument. This function must be used with care, taking into account the following points:

  1. On return, ap_save_brigade guarantees that all the buckets in the returned brigade will represent data mapped into memory. If given an input brigade containing, for example, a PIPE bucket, ap_save_brigade will consume an arbitrary amount of memory to store the entire output of the pipe.
  2. When ap_save_brigade reads from buckets which cannot be setaside, it will always perform blocking reads, removing the opportunity to use Non-blocking bucket reads.
  3. If ap_save_brigade is used without passing a non-NULL "saveto" (destination) brigade parameter, the function will create a new brigade, which may cause memory use to be proportional to content size as described in the Brigade structure section.
Filters must ensure that any buffered data is processed and passed down the filter chain during the last invocation for a given response (a brigade containing an EOS bucket). Otherwise such data will be lost.

Non-blocking bucket reads

The apr_bucket_read function takes an apr_read_type_e argument which determines whether a blocking or non-blocking read will be performed from the data source. A good filter will first attempt to read from every data bucket using a non-blocking read; if that fails with APR_EAGAIN, then send a FLUSH bucket down the filter chain, and retry using a blocking read.

This mode of operation ensures that any filters further down the filter chain will flush any buffered buckets if a slow content source is being used.

A CGI script is an example of a slow content source which is implemented as a bucket type. mod_cgi will send PIPE buckets which represent the output from a CGI script; reading from such a bucket will block when waiting for the CGI script to produce more output.

Example code using non-blocking bucket reads

apr_bucket *e;
apr_read_type_e mode = APR_NONBLOCK_READ;

while ((e = APR_BRIGADE_FIRST(bb)) != APR_BRIGADE_SENTINEL(bb)) {
    apr_status_t rv;

    rv = apr_bucket_read(e, &data, &length, mode);
    if (rv == APR_EAGAIN && mode == APR_NONBLOCK_READ) {

        /* Pass down a brigade containing a flush bucket: */
        APR_BRIGADE_INSERT_TAIL(tmpbb, apr_bucket_flush_create(...));
        rv = ap_pass_brigade(f->next, tmpbb);
        apr_brigade_cleanup(tmpbb);
        if (rv != APR_SUCCESS) return rv;

        /* Retry, using a blocking read. */
        mode = APR_BLOCK_READ;
        continue;
    }
    else if (rv != APR_SUCCESS) {
        /* handle errors */
    }

    /* Next time, try a non-blocking read first. */
    mode = APR_NONBLOCK_READ;
    ...
}

Ten rules for output filters

In summary, here is a set of rules for all output filters to follow:

  1. Output filters should not pass empty brigades down the filter chain, but should be tolerant of being passed empty brigades.
  2. Output filters must pass all metadata buckets down the filter chain; FLUSH buckets should be respected by passing any pending or buffered buckets down the filter chain.
  3. Output filters should ignore any buckets following an EOS bucket.
  4. Output filters must process a fixed amount of data at a time, to ensure that memory consumption is not proportional to the size of the content being filtered.
  5. Output filters should be agnostic with respect to bucket types, and must be able to process buckets of unfamiliar type.
  6. After calling ap_pass_brigade to pass a brigade down the filter chain, output filters should call apr_brigade_cleanup to ensure the brigade is empty before reusing that brigade structure; output filters should never use apr_brigade_destroy to "destroy" brigades.
  7. Output filters must setaside any buckets which are preserved beyond the duration of the filter function.
  8. Output filters must not ignore the return value of ap_pass_brigade, and must return appropriate errors back up the filter chain.
  9. Output filters must only create a fixed number of bucket brigades for each response, rather than one per invocation.
  10. Output filters should first attempt non-blocking reads from each data bucket, and send a FLUSH bucket down the filter chain if the read blocks, before retrying with a blocking read.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache HTTP Server 2.x Thread Safety Issues - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4 > Developer Documentation

Apache HTTP Server 2.x Thread Safety Issues

When using any of the threaded mpms in the Apache HTTP Server 2.x it is important that every function called from Apache be thread safe. When linking in 3rd party extensions it can be difficult to determine whether the resulting server will be thread safe. Casual testing generally won't tell you this either as thread safety problems can lead to subtle race conditions that may only show up in certain conditions under heavy load.

Global and static variables

When writing your module or when trying to determine if a module or 3rd party library is thread safe there are some common things to keep in mind.

First, you need to recognize that in a threaded model each individual thread has its own program counter, stack and registers. Local variables live on the stack, so those are fine. You need to watch out for any static or global variables. This doesn't mean that you are absolutely not allowed to use static or global variables. There are times when you actually want something to affect all threads, but generally you need to avoid using them if you want your code to be thread safe.

In the case where you have a global variable that needs to be global and accessed by all threads, be very careful when you update it. If, for example, it is an incrementing counter, you need to atomically increment it to avoid race conditions with other threads. You do this using a mutex (mutual exclusion). Lock the mutex, read the current value, increment it and write it back and then unlock the mutex. Any other thread that wants to modify the value has to first check the mutex and block until it is cleared.

If you are using APR, have a look at the apr_atomic_* functions and the apr_thread_mutex_* functions.

errno

This is a common global variable that holds the error number of the last error that occurred. If one thread calls a low-level function that sets errno and then another thread checks it, we are bleeding error numbers from one thread into another. To solve this, make sure your module or library defines _REENTRANT or is compiled with -D_REENTRANT. This will make errno a per-thread variable and should hopefully be transparent to the code. It does this by doing something like this:

#define errno (*(__errno_location()))

which means that accessing errno will call __errno_location() which is provided by the libc. Setting _REENTRANT also forces redefinition of some other functions to their *_r equivalents and sometimes changes the common getc/putc macros into safer function calls. Check your libc documentation for specifics. Instead of, or in addition to _REENTRANT the symbols that may affect this are _POSIX_C_SOURCE, _THREAD_SAFE, _SVID_SOURCE, and _BSD_SOURCE.

Common standard troublesome functions

Not only do things have to be thread safe, but they also have to be reentrant. strtok() is an obvious one. You call it the first time with your delimiter which it then remembers and on each subsequent call it returns the next token. Obviously if multiple threads are calling it you will have a problem. Most systems have a reentrant version of the function called strtok_r() where you pass in an extra argument which contains an allocated char * which the function will use instead of its own static storage for maintaining the tokenizing state. If you are using APR you can use apr_strtok().

crypt() is another function that tends to not be reentrant, so if you run across calls to that function in a library, watch out. On some systems it is reentrant though, so it is not always a problem. If your system has crypt_r() chances are you should be using that, or if possible simply avoid the whole mess by using md5 instead.

Common 3rd Party Libraries

The following is a list of common libraries that are used by 3rd party Apache modules. You can check to see if your module is using a potentially unsafe library by using tools such as ldd(1) and nm(1). For PHP, for example, try this:

% ldd libphp4.so
libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)
libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)
libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)
libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)
libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)
libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)
libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)
libming.so => /usr/lib/libming.so (0x40449000)
libm.so.6 => /lib/libm.so.6 (0x40487000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)
libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)
libssl.so.2 => /lib/libssl.so.2 (0x40532000)
libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)
libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)
libdl.so.2 => /lib/libdl.so.2 (0x40634000)
libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)
libc.so.6 => /lib/libc.so.6 (0x4064b000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)

In addition to these libraries you will need to have a look at any libraries linked statically into the module. You can use nm(1) to look for individual symbols in the module.

Library List

Please drop a note to dev@httpd.apache.org if you have additions or corrections to this list.

Library | Version | Thread Safe? | Notes
ASpell/PSpell |  | ? |
Berkeley DB | 3.x, 4.x | Yes | Be careful about sharing a connection across threads.
bzip2 |  | Yes | Both low-level and high-level APIs are thread-safe. However, high-level API requires thread-safe access to errno.
cdb |  | ? |
C-Client |  | Perhaps | c-client uses strtok() and gethostbyname() which are not thread-safe on most C library implementations. c-client's static data is meant to be shared across threads. If strtok() and gethostbyname() are thread-safe on your OS, c-client may be thread-safe.
libcrypt |  | ? |
Expat |  | Yes | Need a separate parser instance per thread
FreeTDS |  | ? |
FreeType |  | ? |
GD 1.8.x |  | ? |
GD 2.0.x |  | ? |
gdbm |  | No | Errors returned via a static gdbm_error variable
ImageMagick | 5.2.2 | Yes | ImageMagick docs claim it is thread safe since version 5.2.2 (see Change log).
Imlib2 |  | ? |
libjpeg | v6b | ? |
libmysqlclient |  | Yes | Use mysqlclient_r library variant to ensure thread-safety. For more information, please read http://dev.mysql.com/doc/mysql/en/Threaded_clients.html.
Ming | 0.2a | ? |
Net-SNMP | 5.0.x | ? |
OpenLDAP | 2.1.x | Yes | Use ldap_r library variant to ensure thread-safety.
OpenSSL | 0.9.6g | Yes | Requires proper usage of CRYPTO_num_locks, CRYPTO_set_locking_callback, CRYPTO_set_id_callback
liboci8 (Oracle 8+) | 8.x,9.x | ? |
pdflib | 5.0.x | Yes | PDFLib docs claim it is thread safe; changes.txt indicates it has been partially thread-safe since V1.91: http://www.pdflib.com/products/pdflib-family/pdflib/.
libpng | 1.0.x | ? |
libpng | 1.2.x | ? |
libpq (PostgreSQL) | 8.x | Yes | Don't share connections across threads and watch out for crypt() calls
Sablotron | 0.95 | ? |
zlib | 1.1.4 | Yes | Relies upon thread-safe zalloc and zfree functions Default is to use libc's calloc/free which are thread-safe.

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Glossaire - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Glossaire

Ce glossaire définit la terminologie courante relative à Apache en particulier, et aux serveurs web en général. Vous trouverez plus d'informations sur chaque concept dans les liens fournis.

Définitions

Algorithme
Une formule sans ambiguité ou un jeu de règles destinées à résoudre un problème en un nombre fini d'étapes. Les algorithmes de chiffrement sont en général appelés Ciphers.
Algorithme de chiffrement (Cipher)
Un algorithme ou un système de chiffrement des données. Quelques exemples : DES, IDEA, RC4, etc.
Voir : chiffrement SSL/TLS
APR
Voir "Bibliothèques pour la portabilité d'Apache"
Archive Tar (Tarball)
Un paquetage de fichiers rassemblés dans une archive à l'aide de l'utilitaire tar. Les distributions d'Apache sont stockées dans des Archives Tar compressées ou en utilisant pkzip.
Authentification
L'identification formelle d'une entité du réseau comme un serveur, un client, ou un utilisateur.
Voir : Authentification, Autorisation, et contrôle d'accès
Autorité de Certification (Certification Authority) (CA)
Un tiers de confiance habilité à signer des certificats pour des entités du réseau qu'il a authentifiées selon des critères basés sur la sécurité. Les autres entités du réseau peuvent alors utiliser la signature pour vérifier qu'une CA a authentifié le porteur du certificat.
Voir : chiffrement SSL/TLS
Bibliothèques pour la portabilité d'Apache (Apache Portable Runtime) (APR)
Un jeu de bibliothèques qui fournit la plupart des interfaces de base entre le serveur et le système d'exploitation. APR est développé parallèlement au serveur HTTP Apache comme projet indépendant.
Voir : Apache Portable Runtime Project
Certificat (Certificate)
Un ensemble de données servant à authentifier des entités du réseau comme un serveur ou un client. Un certificat contient des ensembles d'informations X509 à propos de son propriétaire (appelé sujet/subject) et de l'Autorité de Certification (Certification Authority) ou CA signataire (appelée le fournisseur/issuer), ainsi que la clé publique (public key) du propriétaire et la signature de la CA. Les entités du réseau vérifient ces signatures en utilisant les certificats des Autorités de Certification.
Voir : chiffrement SSL/TLS
Chiffrement à Clé Publique (Public Key Cryptography)
L'étude et l'application des systèmes de chiffrement asymétriques, qui utilisent une clé pour le chiffrement et une autre pour le déchiffrement. Les deux clés correspondantes constituent une paire de clés. Appelé aussi chiffrement asymétrique.
Voir : chiffrement SSL/TLS
Clé Privée (Private Key)
La clé secrète dans un système de chiffrement à clé publique, utilisée pour déchiffrer les messages entrants et signer les messages sortants.
Voir : chiffrement SSL/TLS
Clé Publique (Public Key)
La clé accessible au public dans un système de Chiffrement à clé publique, utilisée pour chiffrer les messages destinés uniquement à son propriétaire et déchiffrer les signatures faites par son propriétaire.
Voir : chiffrement SSL/TLS
CONNECT
Une méthode HTTP pour encapsuler des données brutes dans HTTP. Elle peut aussi être utilisée pour encapsuler d'autres protocoles, comme le protocole SSL.
Contexte (Context)
Une portion des fichiers de configuration dans laquelle certains types de directives sont autorisés.
Voir : Termes utilisés pour décrire les directives d'Apache
Contrôle d'accès (Access Control)
La restriction d'accès à des zones du réseau. Habituellement dans un contexte Apache, la restriction d'accès à certaines URLs.
Voir : Authentification, Autorisation et Contrôle d'accès
Couche des Points de connexion Sécurisés (Secure Sockets Layer) (SSL)
Un protocole créé par Netscape Communications Corporation pour l'authentification et le chiffrement généraux des communications dans les réseaux TCP/IP. L'utilisation la plus connue est HTTPS, autrement dit le Protocole de Transfert Hypertexte (HTTP) au dessus de SSL.
Voir : chiffrement SSL/TLS
Sous-requête
Apache possède une API des sous-requêtes pour les modules qui permettent l'évaluation complète ou partielle par le serveur de chemins d'autres systèmes de fichiers ou d'URL. Par exemple, la directive DirectoryIndex, les modules mod_autoindex et mod_include utilisent cette API.
Cryptographie Symétrique (Symmetric Cryptography)
L'étude et l'application des Algorithmes de chiffrement qui utilisent une clé secrète unique pour les opérations de chiffrement et de déchiffrement.
Voir : chiffrement SSL/TLS
Dégradé pour l'exportation (Export-Crippled)
Diminué en terme de puissance cryptographique (et de sécurité) afin de respecter les Règles de l'Administration des Exportations des Etats-Unis (Export Administration Regulations ou EAR). Les logiciels de cryptographie dégradés pour l'exportation sont limités à une clé de petite taille, et produisent un Texte crypté qui peut en général être décrypté par force brute.
Voir : chiffrement SSL/TLS
Demande de signature de certificat (Certificate Signing Request) (CSR)
La soumission d'un certificat non signé à une Autorité de certification, qui le signe avec la Clé privée de leur Certificat de CA. Une fois le CSR signé, il devient un vrai certificat.
Voir : chiffrement SSL/TLS
Directive
Une commande de configuration qui contrôle un ou plusieurs aspects du comportement d'Apache. Les directives sont placées dans le Fichier de configuration
Voir : Index des directives
Directive de configuration (Configuration Directive)
Voir : Directive
En-tête (Header)
La partie de la requête et de la réponse HTTP qui est envoyée avant le contenu proprement dit, et contient des méta-informations décrivant le contenu.
Expression Rationnelle (Regular Expression) (Regex)
Une méthode pour décrire un modèle sous forme de texte - par exemple, "tous les mots qui commencent par la lettre A" ou "tous les numéros de téléphone à 10 chiffres" ou encore "Toutes les phrases contenant 2 virgules, et aucun Q majuscule". Les expressions rationnelles sont très utiles dans Apache car elles vous permettent d'appliquer certains attributs à des ensembles de fichiers ou ressources avec une grande flexibilité - par exemple, tous les fichiers .gif et .jpg situés dans tout répertoire nommé "images", pourraient être enregistrés comme "/images/.*(jpg|gif)$". Lorsque l'on utilise des expressions rationnelles pour la substitution de chaînes, les variables spéciales $1 ... $9 contiennent des références arrières vers les parties regroupées (entre parenthèses) de l'expression qui correspond. La variable spéciale $0 contient une référence arrière vers l'ensemble de l'expression qui correspond. Pour insérer un caractère littéral "dollar" dans la chaîne de remplacement, il faut l'échapper avec un anti-slash. Pour des raisons historiques, la variable & peut être utilisée en tant qu'alias de $0 dans certains cas, mais ceci n'est plus possible depuis la version 2.3.6. Apache utilise les Expressions Rationnelles Compatibles avec Perl fournies par la librairie PCRE. Vous trouverez plus d'information à propos de la syntaxe des expressions rationnelles PCRE sur ce site, ou dans le Wikipedia de la PCRE.
Fichier de configuration (Configuration File)
Un fichier texte contenant des Directives qui contrôlent la configuration d'Apache.
Voir : Fichiers de configuration
Filtre (Filter)
Un traitement appliqué aux données envoyées ou reçues par le serveur. Les filtres en entrée traitent les données envoyées au serveur par le client, alors que les filtres en sortie traitent les documents sur le serveur avant qu'ils soient envoyés au client. Par exemple, le filtre en sortie INCLUDES traite les documents pour les Server Side Includes (Inclusions côté Serveur) .
Voir : Filtres
Gestionnaire (Handler)
Une représentation interne à Apache de l'action à entreprendre quand un fichier est appelé. En général, les fichiers ont des gestionnaires implicites, basés sur le type de fichier. Normalement, tous les fichiers sont directement servis par le serveur, mais certains types de fichiers sont "gérés" séparément. Par exemple, le gestionnaire cgi-script désigne les fichiers qui doivent être traités comme CGIs.
Voir : Utilisation des gestionnaires d'Apache
Hachage (Hash)
Un algorithme mathématique à sens unique, irréversible, générant une chaîne de longueur fixe à partir d'une autre chaîne de longueur quelconque. Des chaînes différentes en entrée vont normalement produire des chaînes différentes en sortie (selon la fonction de hachage).
Hébergement Virtuel (Virtual Hosting)
Servir des sites web multiples en utilisant une seule instance d'Apache. Les Hôtes virtuels basés sur IP différencient les sites web en se basant sur leur adresse IP, alors que les Hôtes virtuels basés sur le nom utilisent uniquement le nom d'hôte et peuvent en conséquence héberger de nombreux sites avec la même adresse IP.
Voir la Documentation des Hôtes Virtuels d'Apache
.htaccess
Un fichier de configuration placé à un certain niveau de l'arborescence du site web, et appliquant des directives de configuration au répertoire dans lequel il est placé, ainsi qu'à tous ses sous-répertoires. En dépit de son nom, ce fichier peut contenir pratiquement tout type de directive, et pas seulement des directives de contrôle d'accès.
Voir : Fichiers de configuration
httpd.conf
Le fichier de configuration principal d'Apache. Sa localisation par défaut est /usr/local/apache2/conf/httpd.conf, mais ceci peut être changé en utilisant des options de compilation ou d'exécution.
Voir : Fichiers de configuration
HTTPS
Le Protocole de Transfert Hypertexte (Sécurisé), le mécanisme de communication cryptée standard sur le World Wide Web. Il s'agit en fait de HTTP au dessus de SSL.
Voir : chiffrement SSL/TLS
Identificateur de Ressource Uniformisé (Uniform Resource Identifier) (URI)
Une chaîne de caractères compacte servant à identifier une ressource abstraite ou physique. Elle est formellement définie par la RFC 2396. Les URIs utilisées sur le world-wide web sont souvent appelées URLs.
Inclusions Côté Serveur (Server Side Includes) (SSI)
Une technique permettant d'englober des directives de traitement dans des fichiers HTML.
Voir : Introduction aux Inclusions Côté Serveur
Indication du nom du serveur (SNI)
Une fonctionnalité SSL permettant de spécifier le nom du serveur désiré dans le message initial de la négociation SSL, de façon à ce que le serveur web puisse choisir la bonne configuration de serveur virtuel à utiliser pendant le déroulement de la négociation SSL. Cette fonctionnalité a été ajoutée à SSL lorsque sont apparues les extensions TLS, RFC 3546.
Voir la FAQ SSL et la RFC 3546
Interface commune avec les programmes externes (Common Gateway Interface) (CGI)
La définition standard d'une interface entre un serveur web et un programme externe pour permettre à ce dernier de traiter des requêtes. Il existe une RFC informationnelle qui en couvre les spécificités.
Voir : Contenu dynamique avec CGI
Localisation de Ressource Uniformisée (Uniform Resource Locator) (URL)
Le nom/adresse d'une ressource sur l'Internet. Il s'agit du terme informel commun pour ce qui est formellement défini comme Identificateur de Ressource Uniformisé. Les URLs sont généralement construites selon un schéma, comme http ou https, un nom d'hôte, et un chemin. Une URL pour cette page pourrait être http://httpd.apache.org/docs/2.4/glossary.html.
Mandataire (Proxy)
Un serveur intermédiaire qui se situe entre le client et le serveur d'origine. Il prend en compte les requêtes des clients, les transmet au serveur d'origine, puis renvoie la réponse du serveur d'origine au client. Si plusieurs clients demandent le même contenu, le mandataire peut l'extraire de son cache, plutôt que le demander au serveur d'origine à chaque fois, ce qui réduit le temps de réponse.
Voir : mod_proxy
Mandataire inverse (Reverse Proxy)
Un serveur mandataire qui est vu du client comme un serveur d'origine. Ceci peut s'avérer utile pour dissimuler le serveur d'origine réel au client pour des raisons de sécurité, ou pour répartir la charge.
Méthode (Method)
Dans le contexte HTTP, une action à effectuer sur une ressource spécifiée dans la ligne de requête par le client. Parmi les méthodes disponibles dans HTTP, on trouve GET, POST, et PUT.
Module
Une partie indépendante d'un programme. De nombreuses fonctionnalités d'Apache sont fournies par des modules que vous pouvez choisir d'inclure ou d'exclure. Les modules qui sont compilés dans le binaire httpd sont appelés modules statiques, alors que les modules qui existent séparément et peuvent être chargés optionnellement à l'exécution sont appelés modules dynamiques ou DSOs. Les modules qui sont inclus par défaut sont appelés modules de base. De nombreux modules disponibles pour Apache ne se trouvent pas dans l'archive du Serveur HTTP Apache . Il sont appelés modules tiers.
Voir : Index des modules
Mot de Passe (Pass Phrase)
Le mot ou la phrase qui protège les fichiers de clés privées. Il empêche les utilisateurs non autorisés de les déchiffrer. En général, il s'agit simplement de la clé secrète de chiffrement/déchiffrement utilisée pour les Algorithmes de chiffrement.
Voir : chiffrement SSL/TLS
Nom de domaine entièrement qualifié (Fully-Qualified Domain-Name) (FQDN)
Le nom unique d'une entité du réseau, comprenant un nom d'hôte et un nom de domaine qui peuvent être résolus en une adresse IP. Par exemple, www est un nom d'hôte, example.com est un nom de domaine, et www.example.com est un nom de domaine entièrement qualifié.
Nombre Magique des Modules (Module Magic Number) (MMN)
Le Nombre Magique des Modules est une constante définie dans le code source d'Apache et associée à la compatibilité binaire des modules. Sa valeur est modifiée quand des structures internes d'Apache, des appels de fonctions et d'autres parties significatives de l'API sont modifiées de telle façon que la compatibilité binaire ne peut plus être garantie. En cas de changement de MMN, tous les modules tiers doivent être au moins recompilés, et parfois même légèrement modifiés afin de pouvoir fonctionner avec la nouvelle version d'Apache.
Objet Dynamique Partagé (Dynamic Shared Object) (DSO)
Modules compilés en dehors du binaire Apache httpd et qui peuvent être chargés à la demande.
Voir : Support des objets dynamiques partagés
OpenSSL
L'ensemble d'outils Open Source pour SSL/TLS
Voir http://www.openssl.org/#
Outil de gestion des extensions Apache (APache eXtension Tool) (apxs)
Un script Perl qui aide à la compilation des sources de module sous forme d'Objets Dynamiques Partagés (Dynamic Shared Objects ou DSOs) et facilite leur installation dans le serveur Web Apache.
Voir : Page de manuel : apxs
Plein Texte (Plaintext)
Le texte non chiffré.
Protocole de Transfert Hypertexte (HyperText Transfer Protocol) (HTTP)
Le protocole de transmission standard utilisé sur le World Wide Web. Apache implémente la version 1.1 du protocole, référencée comme HTTP/1.1 et définie par la RFC 2616.
Résumé de message (Message Digest)
Un hachage du message, qui peut être utilisé pour vérifier que son contenu n'a pas été altéré durant le transfert.
Voir : chiffrement SSL/TLS
Sécurité de la couche Transport (Transport Layer Security) (TLS)
Le protocole successeur de SSL, créé par l'Internet Engineering Task Force (IETF) pour l'authentification et le chiffrement généraux des communications dans les réseaux TCP/IP. TLS version 1 est pratiquement identique à SSL version 3.
Voir : chiffrement SSL/TLS
Session
Les informations sur le contexte d'une communication en général.
Signature numérique (Digital Signature)
Un bloc de texte crypté qui valide un certificat ou un autre fichier. Une Autorité de certification crée une signature en générant une empreinte de la Clé publique fournie avec le Certificat; la CA chiffre ensuite l'empreinte avec sa propre Clé privée. Seule la clé publique de la CA peut décrypter la signature, ce qui permet de vérifier que la CA a bien authentifié l'entité du réseau qui possède le Certificat.
Voir : chiffrement SSL/TLS
SSLeay
La bibliothèque originelle d'implémentation de SSL/TLS développée par Eric A. Young
Texte crypté (Ciphertext)
Le résultat du passage d'un document Plaintext (Plein texte) par un Cipher.
Voir : chiffrement SSL/TLS
Type MIME (MIME-type)
Une méthode pour décrire le type de document transmis. Son nom vient du fait que son format est issu des Multipurpose Internet Mail Extensions (Extensions Multi-usages de la Messagerie par Internet) . Il comprend un type majeur et un type mineur, séparés par un slash (barre oblique). On trouve entre autres types text/html, image/gif, et application/octet-stream. Dans HTTP, le type MIME est transmis dans l' en-tête Content-Type.
Voir : mod_mime
Variable d'environnement (Environment Variable) (env-variable)
Ce sont des variables nommées gérées par le shell du système d'exploitation, et servant au stockage d'informations et à la communication entre les programmes. Apache possède aussi des variables internes considérées comme variables d'environnement, mais stockées dans des structures internes à Apache, et non dans l'environnement du shell.
Voir : Les variables d'environnement dans Apache
X.509
Une norme de certificat d'authentification recommandée par l'International Telecommunication Union (ITU-T) et utilisée pour l'authentification SSL/TLS.
Voir : chiffrement SSL/TLS


Index des modules - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Index des modules

Ci-dessous se trouve la liste de tous les modules qui font partie de la distribution du serveur HTTP Apache. Voir aussi la liste alphabétique complète de toutes les directives du serveur HTTP Apache.

Voir aussi

  • Modules multi-processus (MPMs)
  • Document de référence rapide des directives

Fonctionalités de Base et Modules Multi-Processus (MPM)

core
Fonctionnalités de base du serveur HTTP Apache toujours disponibles
mpm_common
Une série de directives implémentées par plusieurs modules multi-processus (MPM)
event
Une variante du MPM worker conçue pour ne mobiliser des threads que pour les connexions en cours de traitement
mpm_netware
Module multi-processus implémentant un serveur web basé exclusivement sur les threads et optimisé pour Novell NetWare
mpmt_os2
MPM hybride multi-processus, multi-thread pour OS/2
prefork
Implémente un serveur web avec démarrage anticipé de processus, sans thread
mpm_winnt
Module multi-processus optimisé pour Windows NT.
worker
Module multi-processus implémentant un serveur web hybride multi-processus multi-thread

Autres Modules

A | B | C | D | E | F | H | I | L | M | N | P | R | S | U | V | W | X

mod_access_compat
Autorisations de groupe à base de nom d'hôte (nom ou adresse IP)
mod_actions
Exécution des scripts CGI en fonction du type de média ou de la méthode de requête.
mod_alias
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
mod_allowmethods
Ce module permet de restreindre aisément les méthodes HTTP pouvant être utilisées sur le serveur
mod_asis
Envoie des fichiers contenant leurs propres en-têtes HTTP
mod_auth_basic
Authentification HTTP de base
mod_auth_digest
Authentification utilisateur utilisant les condensés MD5
mod_auth_form
Authentification à l'aide d'un formulaire
mod_authn_anon
Permet un accès "anonyme" à des zones protégées
mod_authn_core
Le noyau de l'authentification
mod_authn_dbd
Authentification utilisateur à l'aide d'une base de données SQL
mod_authn_dbm
Authentification utilisateur utilisant des fichiers DBM
mod_authn_file
Authentification utilisateur à l'aide de fichiers texte
mod_authn_socache
Gère un cache des données d'authentification pour diminuer la charge des serveurs d'arrière-plan
mod_authnz_fcgi
Allows a FastCGI authorizer application to handle Apache httpd authentication and authorization
mod_authnz_ldap
Permet d'utiliser un annuaire LDAP pour l'authentification HTTP de base.
mod_authz_core
Autorisation basique
mod_authz_dbd
Autorisation en groupe et reconnaissance d'identité avec base SQL
mod_authz_dbm
Autorisation basée sur les groupes à l'aide de fichiers DBM
mod_authz_groupfile
Autorisation basée sur les groupes à l'aide de fichiers textes
mod_authz_host
Autorisations de groupe basées sur l'hôte (nom ou adresse IP)
mod_authz_owner
Autorisation basée sur l'appartenance des fichiers
mod_authz_user
Autorisation basée sur l'utilisateur
mod_autoindex
Génère automatiquement des index de répertoires d'une manière similaire à la commande Unix ls, ou à la commande shell Win32 dir
mod_brotli
Compress content via Brotli before it is delivered to the client
mod_buffer
Support de la mise en tampon des requêtes
mod_cache
Filtre de mise en cache HTTP conforme à la RFC 2616
mod_cache_disk
Module de stockage sur disque pour le filtre de mise en cache HTTP.
mod_cache_socache
Module de stockage à base de cache d'objets partagés (socache) pour le filtre de mise en cache HTTP.
mod_cern_meta
La sémantique des métafichiers du serveur httpd du CERN
mod_cgi
Exécution des scripts CGI
mod_cgid
Exécution des scripts CGI par l'intermédiaire d'un démon CGI externe
mod_charset_lite
Spécifie dans quel jeu de caractère doivent s'effectuer les traductions ou les réencodages
mod_data
Convertit un corps de réponse en URL de type données RFC2397
mod_dav
Fonctionnalité de création et gestion de versions de documents via le web (WebDAV)
mod_dav_fs
Implémente le fournisseur filesystem pour mod_dav
mod_dav_lock
Module de verrouillage générique pour mod_dav
mod_dbd
Gestion des connexions à une base de données SQL
mod_deflate
Comprime le contenu avant de le servir au client
mod_dialup
Envoie le contenu statique avec une bande passante limitée définie par les différents standards des anciens modems.
mod_dir
Permet la redirection des adresses se terminant par un répertoire sans slash de fin et la mise à disposition des fichiers index de répertoire
mod_dumpio
Enregistre toutes les entrées/sorties dans le journal des erreurs de la manière souhaitée.
mod_echo
Un simple serveur d'écho pour illustrer les modules de protocole
mod_env
Modifie l'environnement transmis aux scripts CGI et aux pages SSI
mod_example_hooks
Illustration de l'API des modules Apache
mod_expires
Génération des en-têtes HTTP Expires et Cache-Control en fonction de critères spécifiés par l'utilisateur
mod_ext_filter
Fait traiter le corps de la réponse par un programme externe avant de l'envoyer au client
mod_file_cache
Mise en cache mémoire d'une liste statique de fichiers
mod_filter
Module de configuration de filtre intelligent sensible au contexte
mod_headers
Personnalisation des en-têtes de requêtes et de réponses HTTP
mod_heartbeat
Envoie des messages d'état au mandataire frontal
mod_heartmonitor
Moniteur centralisé pour les serveurs d'origine mod_heartbeat
mod_http2
Support for the HTTP/2 transport layer
mod_ident
Recherche d'identité conformément à la RFC 1413
mod_imagemap
Traitement des cartes des zones interactives d'une image (imagemaps) au niveau du serveur
mod_include
Documents html interprétés par le serveur (Server Side Includes ou SSI)
mod_info
Affiche une présentation complète de la configuration du serveur
mod_isapi
Extensions ISAPI dans Apache pour Windows
mod_lbmethod_bybusyness
Algorithme de planification avec répartition de charge de l'attribution des requêtes en attente pour le module mod_proxy_balancer
mod_lbmethod_byrequests
Algorithme de planification avec répartition de charge du traitement des requêtes pour le module mod_proxy_balancer
mod_lbmethod_bytraffic
Algorithme de planification avec répartition de charge en fonction d'un niveau de trafic pour le module mod_proxy_balancer
mod_lbmethod_heartbeat
Algorithme d'ordonnancement de répartition de charge pour mod_proxy_balancer basé sur le comptage de trafic Heartbeat
mod_ldap
Conservation des connexions LDAP et services de mise en cache du résultat à destination des autres modules LDAP
mod_log_config
Journalisation des requêtes envoyées au serveur
mod_log_debug
Journalisation supplémentaire à des fins de débogage
mod_log_forensic
Journalisation légale des requêtes envoyées au serveur
mod_logio
Journalisation des octets en entrée et en sortie pour chaque requête
mod_lua
Fournit des points d'entrée Lua dans différentes parties du traitement des requêtes httpd
mod_macro
Ce module permet d'utiliser des macros dans les fichiers de configuration Apache.
mod_md
Managing domains across virtual hosts, certificate provisioning via the ACME protocol
mod_mime
Associe les extensions des fichiers demandés avec l'action déclenchée par ces fichiers et avec leur contenu (type MIME, langue, jeu de caractère et codage)
mod_mime_magic
Détermine le type MIME d'un fichier à partir de quelques octets de son contenu
mod_negotiation
Effectue la négociation de contenu
mod_nw_ssl
Active le chiffrement SSL pour Netware
mod_privileges
Support des privilèges de Solaris et de l'exécution des serveurs virtuels sous différents identifiants utilisateurs.
mod_proxy
Serveur mandataire/passerelle multi-protocole
mod_proxy_ajp
Module de support AJP pour mod_proxy
mod_proxy_balancer
Extension de mod_proxy pour le support de la répartition de charge
mod_proxy_connect
Extension de mod_proxy pour le traitement des requêtes CONNECT
mod_proxy_express
Extension à mod_proxy pour le mandatement dynamique inverse de masse
mod_proxy_fcgi
Module fournissant le support de FastCGI à mod_proxy
mod_proxy_fdpass
Module fournissant le support des processus externes fdpass à mod_proxy
mod_proxy_ftp
Module fournissant le support FTP à mod_proxy
mod_proxy_hcheck
Dynamic health check of Balancer members (workers) for mod_proxy
mod_proxy_html
Réécrit les liens HTML afin de s'assurer qu'ils soient bien adressables depuis les réseaux des clients dans un contexte de mandataire.
mod_proxy_http
Module fournissant le support HTTP à mod_proxy
mod_proxy_http2
HTTP/2 support module for mod_proxy
mod_proxy_scgi
Module fournissant le support de la passerelle SCGI à mod_proxy
mod_proxy_uwsgi
UWSGI gateway module for mod_proxy
mod_proxy_wstunnel
Websockets support module for mod_proxy
mod_ratelimit
Limitation de la bande passante pour les clients
mod_reflector
Renvoie un corps de requête comme réponse via la pile de filtres en sortie.
mod_remoteip
Remplace l'adresse IP du client pour la requête par l'adresse IP présentée par un mandataire ou un répartiteur de charge via les en-têtes de la requête.
mod_reqtimeout
Définit le délai maximum et le taux minimum de transfert des données pour la réception des requêtes
mod_request
Filtres permettant de traiter et de mettre à disposition les corps de requêtes HTTP
mod_rewrite
Ce module fournit un moteur de réécriture à base de règles permettant de réécrire les URLs des requêtes à la volée
mod_sed
Filtre les contenus en entrée (requêtes) et en sortie (réponses) en utilisant la syntaxe de sed
mod_session
Support des sessions
mod_session_cookie
Support des sessions basé sur les cookies
mod_session_crypto
Support du chiffrement des sessions
mod_session_dbd
Support des session basé sur DBD/SQL
mod_setenvif
Permet de définir des variables d'environnement en fonction de certainescaractéristiques de la requête
mod_slotmem_plain
Fournisseur de mémoire partagée à base de slots.
mod_slotmem_shm
Fournisseur de mémoire partagée basée sur les slots.
mod_so
Chargement de modules ou de code exécutable au cours du démarrage ou du redémarrage du serveur
mod_socache_dbm
Fournisseur de cache d'objets partagés basé sur DBM.
mod_socache_dc
Fournisseur de cache d'objets partagés basé sur dc.
mod_socache_memcache
Fournisseur de cache d'objets partagés basé sur Memcache.
mod_socache_shmcb
Fournisseur de cache d'objets partagés basé sur shmcb.
mod_speling
Tente de corriger les erreurs de casse dans les URLs ou les fautes de frappe mineures.
mod_ssl
Chiffrement de haut niveau basé sur les protocoles Secure Sockets Layer (SSL) et Transport Layer Security (TLS)
mod_status
Fournit des informations sur les performances et l'activité du serveur
mod_substitute
Effectue des opérations de recherche/remplacement sur les corps de réponses
mod_suexec
Permet l'exécution des scripts CGI sous l'utilisateur et le groupe spécifiés
mod_unique_id
Fournit une variable d'environnement contenant un identifiant unique pour chaque requête
mod_unixd
Sécurité de base (nécessaire) pour les plates-formes de la famille Unix.
mod_userdir
Répertoires propres à un utilisateur
mod_usertrack
Journalisation Clickstream des liens parcourus par un utilisateur sur un site
mod_version
Version dependent configuration
mod_vhost_alias
Permet de configurer dynamiquement l'hébergement virtuel de masse
mod_watchdog
provides infrastructure for other modules to periodically run tasks
mod_xml2enc
Support avancé de l'internationalisation et des jeux de caractères pour les modules de filtrage basés sur libxml2


Index des directives - Serveur Apache HTTP Version 2.4

Index des directives

Toutes les directives Apache disponibles dans la distribution standard d'Apache sont référencées ici. Elles sont décrites en utilisant un format normalisé, et un dictionnaire des termes utilisés dans leurs descriptions est disponible.

Un Document de référence rapide des directives est également disponible. Il donne des détails à propos de chaque directive sous une forme abrégée.

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | Q | R | S | T | U | V | W | X

  • AcceptFilter
  • AcceptPathInfo
  • AccessFileName
  • Action
  • AddAlt
  • AddAltByEncoding
  • AddAltByType
  • AddCharset
  • AddDefaultCharset
  • AddDescription
  • AddEncoding
  • AddHandler
  • AddIcon
  • AddIconByEncoding
  • AddIconByType
  • AddInputFilter
  • AddLanguage
  • AddModuleInfo
  • AddOutputFilter
  • AddOutputFilterByType
  • AddType
  • Alias
  • AliasMatch
  • Allow
  • AllowCONNECT
  • AllowEncodedSlashes
  • AllowMethods
  • AllowOverride
  • AllowOverrideList
  • Anonymous
  • Anonymous_LogEmail
  • Anonymous_MustGiveEmail
  • Anonymous_NoUserID
  • Anonymous_VerifyEmail
  • AsyncRequestWorkerFactor
  • AuthBasicAuthoritative
  • AuthBasicFake
  • AuthBasicProvider
  • AuthBasicUseDigestAlgorithm
  • AuthDBDUserPWQuery
  • AuthDBDUserRealmQuery
  • AuthDBMGroupFile
  • AuthDBMType
  • AuthDBMUserFile
  • AuthDigestAlgorithm
  • AuthDigestDomain
  • AuthDigestNonceLifetime
  • AuthDigestProvider
  • AuthDigestQop
  • AuthDigestShmemSize
  • AuthFormAuthoritative
  • AuthFormBody
  • AuthFormDisableNoStore
  • AuthFormFakeBasicAuth
  • AuthFormLocation
  • AuthFormLoginRequiredLocation
  • AuthFormLoginSuccessLocation
  • AuthFormLogoutLocation
  • AuthFormMethod
  • AuthFormMimetype
  • AuthFormPassword
  • AuthFormProvider
  • AuthFormSitePassphrase
  • AuthFormSize
  • AuthFormUsername
  • AuthGroupFile
  • AuthLDAPAuthorizePrefix
  • AuthLDAPBindAuthoritative
  • AuthLDAPBindDN
  • AuthLDAPBindPassword
  • AuthLDAPCharsetConfig
  • AuthLDAPCompareAsUser
  • AuthLDAPCompareDNOnServer
  • AuthLDAPDereferenceAliases
  • AuthLDAPGroupAttribute
  • AuthLDAPGroupAttributeIsDN
  • AuthLDAPInitialBindAsUser
  • AuthLDAPInitialBindPattern
  • AuthLDAPMaxSubGroupDepth
  • AuthLDAPRemoteUserAttribute
  • AuthLDAPRemoteUserIsDN
  • AuthLDAPSearchAsUser
  • AuthLDAPSubGroupAttribute
  • AuthLDAPSubGroupClass
  • AuthLDAPUrl
  • AuthMerging
  • AuthName
  • AuthnCacheContext
  • AuthnCacheEnable
  • AuthnCacheProvideFor
  • AuthnCacheSOCache
  • AuthnCacheTimeout
  • <AuthnProviderAlias>
  • AuthnzFcgiCheckAuthnProvider
  • AuthnzFcgiDefineProvider
  • AuthType
  • AuthUserFile
  • AuthzDBDLoginToReferer
  • AuthzDBDQuery
  • AuthzDBDRedirectQuery
  • AuthzDBMType
  • <AuthzProviderAlias>
  • AuthzSendForbiddenOnFailure
  • BalancerGrowth
  • BalancerInherit
  • BalancerMember
  • BalancerPersist
  • BrotliAlterETag
  • BrotliCompressionMaxInputBlock
  • BrotliCompressionQuality
  • BrotliCompressionWindow
  • BrotliFilterNote
  • BrowserMatch
  • BrowserMatchNoCase
  • BufferedLogs
  • BufferSize
  • CacheDefaultExpire
  • CacheDetailHeader
  • CacheDirLength
  • CacheDirLevels
  • CacheDisable
  • CacheEnable
  • CacheFile
  • CacheHeader
  • CacheIgnoreCacheControl
  • CacheIgnoreHeaders
  • CacheIgnoreNoLastMod
  • CacheIgnoreQueryString
  • CacheIgnoreURLSessionIdentifiers
  • CacheKeyBaseURL
  • CacheLastModifiedFactor
  • CacheLock
  • CacheLockMaxAge
  • CacheLockPath
  • CacheMaxExpire
  • CacheMaxFileSize
  • CacheMinExpire
  • CacheMinFileSize
  • CacheNegotiatedDocs
  • CacheQuickHandler
  • CacheReadSize
  • CacheReadTime
  • CacheRoot
  • CacheSocache
  • CacheSocacheMaxSize
  • CacheSocacheMaxTime
  • CacheSocacheMinTime
  • CacheSocacheReadSize
  • CacheSocacheReadTime
  • CacheStaleOnError
  • CacheStoreExpired
  • CacheStoreNoStore
  • CacheStorePrivate
  • CGIDScriptTimeout
  • CGIMapExtension
  • CGIPassAuth
  • CGIVar
  • CharsetDefault
  • CharsetOptions
  • CharsetSourceEnc
  • CheckCaseOnly
  • CheckSpelling
  • ChrootDir
  • ContentDigest
  • CookieDomain
  • CookieExpires
  • CookieName
  • CookieStyle
  • CookieTracking
  • CoreDumpDirectory
  • CustomLog
  • Dav
  • DavDepthInfinity
  • DavGenericLockDB
  • DavLockDB
  • DavMinTimeout
  • DBDExptime
  • DBDInitSQL
  • DBDKeep
  • DBDMax
  • DBDMin
  • DBDParams
  • DBDPersist
  • DBDPrepareSQL
  • DBDriver
  • DefaultIcon
  • DefaultLanguage
  • DefaultRuntimeDir
  • DefaultType
  • Define
  • DeflateBufferSize
  • DeflateCompressionLevel
  • DeflateFilterNote
  • DeflateInflateLimitRequestBody
  • DeflateInflateRatioBurst
  • DeflateInflateRatioLimit
  • DeflateMemLevel
  • DeflateWindowSize
  • Deny
  • <Directory>
  • DirectoryCheckHandler
  • DirectoryIndex
  • DirectoryIndexRedirect
  • <DirectoryMatch>
  • DirectorySlash
  • DocumentRoot
  • DTracePrivileges
  • DumpIOInput
  • DumpIOOutput
  • <Else>
  • <ElseIf>
  • EnableExceptionHook
  • EnableMMAP
  • EnableSendfile
  • Error
  • ErrorDocument
  • ErrorLog
  • ErrorLogFormat
  • Example
  • ExpiresActive
  • ExpiresByType
  • ExpiresDefault
  • ExtendedStatus
  • ExtFilterDefine
  • ExtFilterOptions
  • FallbackResource
  • FileETag
  • <Files>
  • <FilesMatch>
  • FilterChain
  • FilterDeclare
  • FilterProtocol
  • FilterProvider
  • FilterTrace
  • ForceLanguagePriority
  • ForceType
  • ForensicLog
  • GlobalLog
  • GprofDir
  • GracefulShutdownTimeout
  • Group
  • H2CopyFiles
  • H2Direct
  • H2EarlyHints
  • H2MaxSessionStreams
  • H2MaxWorkerIdleSeconds
  • H2MaxWorkers
  • H2MinWorkers
  • H2ModernTLSOnly
  • H2Push
  • H2PushDiarySize
  • H2PushPriority
  • H2PushResource
  • H2SerializeHeaders
  • H2StreamMaxMemSize
  • H2TLSCoolDownSecs
  • H2TLSWarmUpSize
  • H2Upgrade
  • H2WindowSize
  • Header
  • HeaderName
  • HeartbeatAddress
  • HeartbeatListen
  • HeartbeatMaxServers
  • HeartbeatStorage
  • HeartbeatStorage
  • HostnameLookups
  • HttpProtocolOptions
  • IdentityCheck
  • IdentityCheckTimeout
  • <If>
  • <IfDefine>
  • <IfModule>
  • <IfVersion>
  • ImapBase
  • ImapDefault
  • ImapMenu
  • Include
  • IncludeOptional
  • IndexHeadInsert
  • IndexIgnore
  • IndexIgnoreReset
  • IndexOptions
  • IndexOrderDefault
  • IndexStyleSheet
  • InputSed
  • ISAPIAppendLogToErrors
  • ISAPIAppendLogToQuery
  • ISAPICacheFile
  • ISAPIFakeAsync
  • ISAPILogNotSupported
  • ISAPIReadAheadBuffer
  • KeepAlive
  • KeepAliveTimeout
  • KeptBodySize
  • LanguagePriority
  • LDAPCacheEntries
  • LDAPCacheTTL
  • LDAPConnectionPoolTTL
  • LDAPConnectionTimeout
  • LDAPLibraryDebug
  • LDAPOpCacheEntries
  • LDAPOpCacheTTL
  • LDAPReferralHopLimit
  • LDAPReferrals
  • LDAPRetries
  • LDAPRetryDelay
  • LDAPSharedCacheFile
  • LDAPSharedCacheSize
  • LDAPTimeout
  • LDAPTrustedClientCert
  • LDAPTrustedGlobalCert
  • LDAPTrustedMode
  • LDAPVerifyServerCert
  • <Limit>
  • <LimitExcept>
  • LimitInternalRecursion
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldSize
  • LimitRequestLine
  • LimitXMLRequestBody
  • Listen
  • ListenBackLog
  • ListenCoresBucketsRatio
  • LoadFile
  • LoadModule
  • <Location>
  • <LocationMatch>
  • LogFormat
  • LogIOTrackTTFB
  • LogLevel
  • LogMessage
  • LuaAuthzProvider
  • LuaCodeCache
  • LuaHookAccessChecker
  • LuaHookAuthChecker
  • LuaHookCheckUserID
  • LuaHookFixups
  • LuaHookInsertFilter
  • LuaHookLog
  • LuaHookMapToStorage
  • LuaHookTranslateName
  • LuaHookTypeChecker
  • LuaInherit
  • LuaInputFilter
  • LuaMapHandler
  • LuaOutputFilter
  • LuaPackageCPath
  • LuaPackagePath
  • LuaQuickHandler
  • LuaRoot
  • LuaScope
  • <Macro>
  • MaxConnectionsPerChild
  • MaxKeepAliveRequests
  • MaxMemFree
  • MaxRangeOverlaps
  • MaxRangeReversals
  • MaxRanges
  • MaxRequestWorkers
  • MaxSpareServers
  • MaxSpareThreads
  • MaxThreads
  • MDBaseServer
  • MDCAChallenges
  • MDCertificateAgreement
  • MDCertificateAuthority
  • MDCertificateProtocol
  • MDDriveMode
  • MDHttpProxy
  • MDMember
  • MDMembers
  • MDMustStaple
  • MDNotifyCmd
  • MDomain
  • <MDomainSet>
  • MDPortMap
  • MDPrivateKeys
  • MDRenewWindow
  • MDRequireHttps
  • MDStoreDir
  • MemcacheConnTTL
  • MergeTrailers
  • MetaDir
  • MetaFiles
  • MetaSuffix
  • MimeMagicFile
  • MinSpareServers
  • MinSpareThreads
  • MMapFile
  • ModemStandard
  • ModMimeUsePathInfo
  • MultiviewsMatch
  • Mutex
  • NameVirtualHost
  • NoProxy
  • NWSSLTrustedCerts
  • NWSSLUpgradeable
  • Options
  • Order
  • OutputSed
  • PassEnv
  • PidFile
  • PrivilegesMode
  • Protocol
  • ProtocolEcho
  • Protocols
  • ProtocolsHonorOrder
  • <Proxy>
  • ProxyAddHeaders
  • ProxyBadHeader
  • ProxyBlock
  • ProxyDomain
  • ProxyErrorOverride
  • ProxyExpressDBMFile
  • ProxyExpressDBMType
  • ProxyExpressEnable
  • ProxyFCGIBackendType
  • ProxyFCGISetEnvIf
  • ProxyFtpDirCharset
  • ProxyFtpEscapeWildcards
  • ProxyFtpListOnWildcard
  • ProxyHCExpr
  • ProxyHCTemplate
  • ProxyHCTPsize
  • ProxyHTMLBufSize
  • ProxyHTMLCharsetOut
  • ProxyHTMLDocType
  • ProxyHTMLEnable
  • ProxyHTMLEvents
  • ProxyHTMLExtended
  • ProxyHTMLFixups
  • ProxyHTMLInterp
  • ProxyHTMLLinks
  • ProxyHTMLMeta
  • ProxyHTMLStripComments
  • ProxyHTMLURLMap
  • ProxyIOBufferSize
  • <ProxyMatch>
  • ProxyMaxForwards
  • ProxyPass
  • ProxyPassInherit
  • ProxyPassInterpolateEnv
  • ProxyPassMatch
  • ProxyPassReverse
  • ProxyPassReverseCookieDomain
  • ProxyPassReverseCookiePath
  • ProxyPreserveHost
  • ProxyReceiveBufferSize
  • ProxyRemote
  • ProxyRemoteMatch
  • ProxyRequests
  • ProxySCGIInternalRedirect
  • ProxySCGISendfile
  • ProxySet
  • ProxySourceAddress
  • ProxyStatus
  • ProxyTimeout
  • ProxyVia
  • QualifyRedirectURL
  • ReadmeName
  • ReceiveBufferSize
  • Redirect
  • RedirectMatch
  • RedirectPermanent
  • RedirectTemp
  • ReflectorHeader
  • RegisterHttpMethod
  • RemoteIPHeader
  • RemoteIPInternalProxy
  • RemoteIPInternalProxyList
  • RemoteIPProxiesHeader
  • RemoteIPProxyProtocol
  • RemoteIPProxyProtocolExceptions
  • RemoteIPTrustedProxy
  • RemoteIPTrustedProxyList
  • RemoveCharset
  • RemoveEncoding
  • RemoveHandler
  • RemoveInputFilter
  • RemoveLanguage
  • RemoveOutputFilter
  • RemoveType
  • RequestHeader
  • RequestReadTimeout
  • Require
  • <RequireAll>
  • <RequireAny>
  • <RequireNone>
  • RewriteBase
  • RewriteCond
  • RewriteEngine
  • RewriteMap
  • RewriteOptions
  • RewriteRule
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • Satisfy
  • ScoreBoardFile
  • Script
  • ScriptAlias
  • ScriptAliasMatch
  • ScriptInterpreterSource
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength
  • ScriptSock
  • SecureListen
  • SeeRequestTail
  • SendBufferSize
  • ServerAdmin
  • ServerAlias
  • ServerLimit
  • ServerName
  • ServerPath
  • ServerRoot
  • ServerSignature
  • ServerTokens
  • Session
  • SessionCookieName
  • SessionCookieName2
  • SessionCookieRemove
  • SessionCryptoCipher
  • SessionCryptoDriver
  • SessionCryptoPassphrase
  • SessionCryptoPassphraseFile
  • SessionDBDCookieName
  • SessionDBDCookieName2
  • SessionDBDCookieRemove
  • SessionDBDDeleteLabel
  • SessionDBDInsertLabel
  • SessionDBDPerUser
  • SessionDBDSelectLabel
  • SessionDBDUpdateLabel
  • SessionEnv
  • SessionExclude
  • SessionHeader
  • SessionInclude
  • SessionMaxAge
  • SetEnv
  • SetEnvIf
  • SetEnvIfExpr
  • SetEnvIfNoCase
  • SetHandler
  • SetInputFilter
  • SetOutputFilter
  • SSIEndTag
  • SSIErrorMsg
  • SSIETag
  • SSILastModified
  • SSILegacyExprParser
  • SSIStartTag
  • SSITimeFormat
  • SSIUndefinedEcho
  • SSLCACertificateFile
  • SSLCACertificatePath
  • SSLCADNRequestFile
  • SSLCADNRequestPath
  • SSLCARevocationCheck
  • SSLCARevocationFile
  • SSLCARevocationPath
  • SSLCertificateChainFile
  • SSLCertificateFile
  • SSLCertificateKeyFile
  • SSLCipherSuite
  • SSLCompression
  • SSLCryptoDevice
  • SSLEngine
  • SSLFIPS
  • SSLHonorCipherOrder
  • SSLInsecureRenegotiation
  • SSLOCSPDefaultResponder
  • SSLOCSPEnable
  • SSLOCSPNoverify
  • SSLOCSPOverrideResponder
  • SSLOCSPProxyURL
  • SSLOCSPResponderCertificateFile
  • SSLOCSPResponderTimeout
  • SSLOCSPResponseMaxAge
  • SSLOCSPResponseTimeSkew
  • SSLOCSPUseRequestNonce
  • SSLOpenSSLConfCmd
  • SSLOptions
  • SSLPassPhraseDialog
  • SSLProtocol
  • SSLProxyCACertificateFile
  • SSLProxyCACertificatePath
  • SSLProxyCARevocationCheck
  • SSLProxyCARevocationFile
  • SSLProxyCARevocationPath
  • SSLProxyCheckPeerCN
  • SSLProxyCheckPeerExpire
  • SSLProxyCheckPeerName
  • SSLProxyCipherSuite
  • SSLProxyEngine
  • SSLProxyMachineCertificateChainFile
  • SSLProxyMachineCertificateFile
  • SSLProxyMachineCertificatePath
  • SSLProxyProtocol
  • SSLProxyVerify
  • SSLProxyVerifyDepth
  • SSLRandomSeed
  • SSLRenegBufferSize
  • SSLRequire
  • SSLRequireSSL
  • SSLSessionCache
  • SSLSessionCacheTimeout
  • SSLSessionTicketKeyFile
  • SSLSessionTickets
  • SSLSRPUnknownUserSeed
  • SSLSRPVerifierFile
  • SSLStaplingCache
  • SSLStaplingErrorCacheTimeout
  • SSLStaplingFakeTryLater
  • SSLStaplingForceURL
  • SSLStaplingResponderTimeout
  • SSLStaplingResponseMaxAge
  • SSLStaplingResponseTimeSkew
  • SSLStaplingReturnResponderErrors
  • SSLStaplingStandardCacheTimeout
  • SSLStrictSNIVHostCheck
  • SSLUserName
  • SSLUseStapling
  • SSLVerifyClient
  • SSLVerifyDepth
  • StartServers
  • StartThreads
  • Substitute
  • SubstituteInheritBefore
  • SubstituteMaxLineLength
  • Suexec
  • SuexecUserGroup
  • ThreadLimit
  • ThreadsPerChild
  • ThreadStackSize
  • TimeOut
  • TraceEnable
  • TransferLog
  • TypesConfig
  • UnDefine
  • UndefMacro
  • UnsetEnv
  • Use
  • UseCanonicalName
  • UseCanonicalPhysicalPort
  • User
  • UserDir
  • VHostCGIMode
  • VHostCGIPrivs
  • VHostGroup
  • VHostPrivs
  • VHostSecure
  • VHostUser
  • VirtualDocumentRoot
  • VirtualDocumentRootIP
  • <VirtualHost>
  • VirtualScriptAlias
  • VirtualScriptAliasIP
  • WatchdogInterval
  • XBitHack
  • xml2EncAlias
  • xml2EncDefault
  • xml2StartParse


Document de référence rapide des directives - Serveur Apache HTTP Version 2.4

Document de référence rapide des directives

Le document de référence rapide des directives montre l'usage, les valeurs par défaut, le statut, et le contexte de chaque directive de configuration d'Apache. Pour plus d'informations sur chacun de ces termes, voir le Dictionnaire des directives.

La première colonne donne le nom de la directive et son usage. Si la directive possède une valeur par défaut, elle est indiquée dans la deuxième colonne. Si la valeur par défaut est trop grande pour pouvoir être affichée, elle sera tronquée et suivie d'un "+".

La troisième colonne énumère les contextes dans lesquels la directive est applicable, et la quatrième indique son statut en accord avec le tableau des légendes ci-dessous.

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | Q | R | S | T | U | V | W | X
s | configuration du serveur
v | serveur virtuel
d | répertoire
h | .htaccess

C | Core
M | MPM
B | Base
E | Extension
X | Expérimental
T | Externe
AcceptFilter protocole filtre d'acceptation |  | s | C
Permet d'optimiser la configuration d'une socket pour l'écoute d'un protocole
AcceptPathInfo On|Off|Default | Default | svdh | C
Les ressources acceptent des informations sous forme d'un nom de chemin en fin de requête.
AccessFileName nom-du-fichier [nom-du-fichier] ... | .htaccess | sv | C
Nom du fichier de configuration distribué
Action type d'action script cgi [virtual] |  | svdh | B
Active un script CGI pour un gestionnaire ou un type de contenu particulier
AddAlt texte fichier [fichier] ... |  | svdh | B
Texte optionnel à afficher à la place d'un icône pour un fichier en fonction de son nom
AddAltByEncoding texte codage MIME [codage MIME] ... |  | svdh | B
Texte optionnel à afficher à la place d'un icône pour un fichier en fonction de son codage MIME
AddAltByType texte type MIME [type MIME] ... |  | svdh | B
Texte optionnel à afficher à la place d'un icône pour un fichier en fonction de son type MIME
AddCharset jeu-car extension [extension] ... |  | svdh | B
Associe les extensions de noms de fichiers spécifiées au jeu de caractères spécifié
AddDefaultCharset On|Off|jeu de caractères | Off | svdh | C
Paramètre jeu de caractères par défaut à ajouter quand le type de contenu d'une réponse est text/plain ou text/html
AddDescription texte [fichier] ... |  | svdh | B
Afficher la description d'un fichier
AddEncoding codage extension [extension] ... |  | svdh | B
Associe les extensions de noms de fichiers données au type de codage spécifié
AddHandler nom-gestionnaire extension [extension] ... |  | svdh | B
Associe les extensions de noms de fichiers données au gestionnaire spécifié
AddIcon icône nom [nom] ... |  | svdh | B
Icône à afficher pour un fichier en fonction de son nom
AddIconByEncoding icône codage MIME [codage MIME] ... |  | svdh | B
Icône à afficher à côté d'un fichier en fonction de son codage MIME
AddIconByType icône type MIME [type MIME] ... |  | svdh | B
Icône à afficher à côté d'un fichier en fonction de son type MIME
AddInputFilter filtre[;filtre...] extension [extension] ... |  | svdh | B
Associe les extensions de noms de fichiers aux filtres spécifiés qui traiteront les requêtes clients
AddLanguage symbole-langue extension [extension] ... |  | svdh | B
Associe l'extension de nom de fichier donnée à la langue spécifié
AddModuleInfo nom-module chaîne |  | sv | E
Ajoute des données supplémentaires aux informations de module affichées par le gestionnaire server-info
AddOutputFilter filtre[;filtre...] extension [extension] ... |  | svdh | B
Associe les extensions de noms de fichiers aux filtres spécifiés qui traiteront les réponses en provenance du serveur
AddOutputFilterByType filtre[;filtre...] type_de_média [type_de_média] ... |  | svdh | B
assigne un filtre en sortie pour un type de média particulier
AddType type-médium extension [extension] ... |  | svdh | B
Associe les extensions de noms de fichiers au type de contenu spécifié
Alias [chemin URL] chemin fichier|chemin répertoire |  | sv | B
Met en correspondance des URLs avec des chemins du système de fichiers
AliasMatch regex chemin fichier|chemin répertoire |  | sv | B
Met en correspondance des URLs avec le système de fichiers en faisant intervenir les expressions rationnelles
Allow from all|hôte|env=[!]variable d'environnement [hôte|env=[!]variable d'environnement] ... |  | dh | E
Spécifie quels hôtes peuvent accéder à une certaine zone du serveur
AllowCONNECT port[-port] [port[-port]] ... | 443 563 | sv | E
Ports autorisés à se CONNECTer à travers le mandataire
AllowEncodedSlashes On|Off|NoDecode | Off | sv | C
Détermine si les séparateurs de chemin encodés sont autorisés à transiter dans les URLs tels quels
AllowMethods reset|HTTP-method [HTTP-method]... | reset | d | X
Restreint l'accès aux méthodes HTTP spécifiées
AllowOverride All|None|type directive [type directive] ... | None à partir de la + | d | C
Types de directives autorisées dans les fichiers .htaccess
AllowOverrideList None|directive [directive-type] ... | None | d | C
Directives autorisées dans les fichiers .htaccess
Anonymous utilisateur [utilisateur] ... |  | dh | E
Définit la liste des identifiants utilisateur autorisés à accéder sans vérification du mot de passe
Anonymous_LogEmail On|Off | On | dh | E
Détermine si le mot de passe fourni sera enregistré dans le journal des erreurs
Anonymous_MustGiveEmail On|Off | On | dh | E
Détermine si l'abscence de mot de passe est autorisée
Anonymous_NoUserID On|Off | Off | dh | E
Détermine si le champ identifiant peut être vide
Anonymous_VerifyEmail On|Off | Off | dh | E
Détermine s'il faut vérifier que le format de l'adresse email fournie comme mot de passe est correct
AsyncRequestWorkerFactor facteur |  | s | M
Limite le nombre de connexions simultanées par thread
AuthBasicAuthoritative On|Off | On | dh | B
Définit si les processus d'autorisation et d'authentification peuvent être confiés à des modules de plus bas niveau
AuthBasicFake off|username [password] |  | dh | B
Authentification de base simulée à l'aide des nom d'utilisateur et mot de passe fournis
AuthBasicProvider nom fournisseur [nom fournisseur] ... | file | dh | B
Définit le(les) fournisseur(s) d'authentification pour cette zone du site web
AuthBasicUseDigestAlgorithm MD5|Off | Off | dh | B
Vérifie les mots de passe auprès des fournisseurs d'authentification à la manière de l'authentification de type Digest.
AuthDBDUserPWQuery requête |  | d | E
Requête SQL servant à vérifier le mot de passe d'un utilisateur
AuthDBDUserRealmQuery requête |  | d | E
Requête SQL servant à vérifier une empreinte de mot de passe pour un utilisateur et un identifiant d'authentification.
AuthDBMGroupFile chemin-fichier |  | dh | E
Définit le nom du fichier de base de données contenant la liste des groupes d'utilisateurs permettant de définir les autorisations des utilisateurs
AuthDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
Définit le type de fichier de base de données utilisé pour stocker les mots de passe
AuthDBMUserFile chemin-fichier |  | dh | E
Définit le nom d'un fichier de base de données pour l'authentification contenant la liste des utilisateurs et de leurs mots de passe
AuthDigestAlgorithm MD5|MD5-sess | MD5 | dh | E
Sélectionne l'algorithme utilisé pour calculer les condensés du défit et de sa réponse
AuthDigestDomain URI [URI] ... |  | dh | E
Les URIs qui se trouvent dans le même espace de protection concernant l'authentification à base de condensés
AuthDigestNonceLifetime secondes | 300 | dh | E
Durée de validité du nombre à valeur unique du serveur (nonce)
AuthDigestProvider nom fournisseur [nom fournisseur] ... | file | dh | E
Définit le(s) fournisseurs(s) d'authentification pour la zone du site web concernée
AuthDigestQop none|auth|auth-int [auth|auth-int] | auth | dh | E
Détermine le niveau de protection fourni par l'authentification à base de condensé
AuthDigestShmemSize taille | 1000 | s | E
La quantité de mémoire partagée à allouer afin de conserver les informations à propos des clients
AuthFormAuthoritative On|Off | On | dh | B
Détermine si l'autorisation et l'authentification sont confiés à des modules de plus bas niveau
AuthFormBody nom du champ |  | d | B
Le nom du champ de formulaire contenant le corps de la requête à effectuer en cas de connexion réussie
AuthFormDisableNoStore On|Off | Off | d | B
Désactive l'en-tête CacheControl no-store sur la page de connexion
AuthFormFakeBasicAuth On|Off | Off | d | B
Simule une en-tête d'authentification de base
AuthFormLocation nom du champ |  | d | B
Le nom du champ de formulaire qui contiendra l'URL vers laquelle l'utilisateur sera redirigé en cas de connexion réussie
AuthFormLoginRequiredLocation url |  | d | B
L'URL de la page vers laquelle on doit être redirigé si une authentification est requise
AuthFormLoginSuccessLocation url |  | d | B
L'URL de la page vers laquelle on doit être redirigé en cas de connexion réussie
AuthFormLogoutLocation uri |  | d | B
L'URL vers laquelle un utilisateur devra être redirigé après s'être déconnecté
AuthFormMethod nom du champ |  | d | B
Le nom du champ de formulaire contenant la méthode de la requête à effectuer en cas de connexion réussie
AuthFormMimetype nom du champ |  | d | B
Le nom du champ de formulaire contenant le type MIME du corps de la requête à effectuer en cas de connexion réussie
AuthFormPassword nom du champ |  | d | B
Le nom du champ de formulaire qui contient le mot de passe de connexion
AuthFormProvider nom fournisseur [nom fournisseur] ... | file | dh | B
Définit le(s) fournisseur(s) d'authentification pour la zone concernée
AuthFormSitePassphrase secret |  | d | B
Court-circuite l'authentification pour les sites à fort trafic
AuthFormSize taille |  | d | B
La taille maximale en octets du formulaire dont seront extraites les informations de connexion
AuthFormUsername nom du champ |  | d | B
Le nom du champ de formulaire qui contient le nom de connexion
AuthGroupFile chemin-fichier |  | dh | B
Définit le nom d'un fichier texte contenant la liste des groupes d'utilisateurs permettant de définir les autorisations des utilisateurs
AuthLDAPAuthorizePrefix préfixe | AUTHORIZE_ | dh | E
Spécifie le préfixe ajouté aux variables d'environnement durant la phase d'autorisation
AuthLDAPBindAuthoritative off|on | on | dh | E
Détermine si l'on doit utiliser d'autres fournisseurs d'authentification lorsque le serveur ne peut pas valider les données d'authentification de l'utilisateur, alors que ce dernier possède un DN.
AuthLDAPBindDN dn |  | dh | E
Un DN optionnel pour se connecter au serveur LDAP
AuthLDAPBindPassword mot-de-passe |  | dh | E
Mot de passe à utiliser en conjonction avec le DN de connexion
AuthLDAPCharsetConfig chemin-fichier |  | s | E
Chemin du fichier de configuration de la correspondance langage/jeu de caractères
AuthLDAPCompareAsUser on|off | off | dh | E
Utilisation des données d'authentification de l'utilisateur pour effectuer les comparaisons pour l'attribution des autorisations
AuthLDAPCompareDNOnServer on|off | on | dh | E
Utilise le serveur LDAP pour comparer les DNs
AuthLDAPDereferenceAliases never|searching|finding|always | always | dh | E
À quel moment le module va déréférencer les alias
AuthLDAPGroupAttribute attribut | member uniquemember + | dh | E
L'attribut LDAP utilisé pour vérifier l'appartenance d'un utilisateur à un groupe.
AuthLDAPGroupAttributeIsDN on|off | on | dh | E
Utilise le DN de l'utilisateur pour vérifier son appartenance à un groupe
AuthLDAPInitialBindAsUser off|on | off | dh | E
Détermine si le serveur effectue la recherche initiale du DN en utilisant le nom propre de l'utilisateur pour l'authentification de base et non de manière anonyme, ou en utilisant des données d'authentification codées en dur pour le serveur
AuthLDAPInitialBindPattern regex substitution | (.*) $1 (nom de l'u + | dh | E
Spécifie la modification a apporter au nom d'utilisateur pour l'authentification de base lors de l'authentification auprès du serveur LDAP pour effectuer une recherche de DN
AuthLDAPMaxSubGroupDepth Nombre | 10 | dh | E
Spécifie la profondeur d'imbrication des sous-groupes maximale prise en compte avant l'abandon de la recherche de l'utilisateur.
AuthLDAPRemoteUserAttribute uid |  | dh | E
Spécifie l'attribut dont la valeur renvoyée au cours de la requête de l'utilisateur sera utilisée pour définir la variable d'environnement REMOTE_USER
AuthLDAPRemoteUserIsDN on|off | off | dh | E
Utilise le DN de l'utilisateur pour définir la variable d'environnement REMOTE_USER
AuthLDAPSearchAsUser on|off | off | dh | E
Utilise les données d'authentification de l'utilisateur pour la recherche des autorisations
AuthLDAPSubGroupAttribute attribut |  | dh | E
Spécifie les noms d'attribut, un par directive, utilisés pour différencier les membres du groupe courant qui sont eux-mêmes des groupes.
AuthLDAPSubGroupClass ObjectClass-LDAP | groupOfNames groupO + | dh | E
Spécifie quelles valeurs d'objectClass LDAP identifient les objets de l'annuaire qui sont des groupes au cours du traitement des sous-groupes.
AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS] |  | dh | E
L'URL permettant de spécifier les paramètres de la recherche LDAP
AuthMerging Off | And | Or | Off | dh | B
Définit la manière dont chaque logique d'autorisation des sections de configuration se combine avec celles des sections de configuration précédentes.
AuthName domaine d'autorisation |  | dh | B
L'identifiant de l'autorisation à utiliser avec l'authentification HTTP
AuthnCacheContext directory|server|chaîne-personnalisée |  | d | B
Spécifie une chaîne de contexte à utiliser dans la clé du cache
AuthnCacheEnable |  | s | B
Active la mise en cache de l'authentification en tout endroit
AuthnCacheProvideFor fournisseur-authn [...] |  | dh | B
Spécifie le fournisseur pour lequel on veut effectuer une mise en cache
AuthnCacheSOCache nom-fournisseur[:arguments-fournisseur] |  | s | B
Sélectionne le fournisseur socache d'arrière-plan à utiliser
AuthnCacheTimeout durée-de-vie (secondes) |  | dh | B
Définit une durée de vie pour les entrées du cache
<AuthnProviderAlias alias-fournisseur> ... </AuthnProviderAlias> |  | s | B
Regroupe un ensemble de directives qui constituent une extension d'un fournisseur d'authentification de base et lui attribue l'alias spécifié
AuthnzFcgiCheckAuthnProvider provider-name|None option ... |  | d | E
Enables a FastCGI application to handle the check_authn authentication hook.
AuthnzFcgiDefineProvider type provider-name backend-address |  | s | E
Defines a FastCGI application as a provider for authentication and/or authorization
AuthType None|Basic|Digest|Form |  | dh | B
Type d'authentification utilisateur
AuthUserFile chemin-fichier |  | dh | B
Définit le nom d'un fichier texte pour l'authentification contenant la liste des utilisateurs et de leurs mots de passe
AuthzDBDLoginToReferer On|Off | Off | d | E
Définit si le client doit être redirigé vers la page d'origine en cas de connexion ou de déconnexion réussie si un en-tête de requête Referer est présent
AuthzDBDQuery requête |  | d | E
Définit la requête SQL pour l'opération requise
AuthzDBDRedirectQuery requête |  | d | E
Définit une requête pour rechercher une page vers laquelle rediriger l'utilisateur après une connexion réussie
AuthzDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
Définit le type de fichier de base de données contenant la liste des groupes d'utilisateurs
<AuthzProviderAlias fournisseur-de-base Alias Paramètres-Require> ... </AuthzProviderAlias> |  | s | B
Regroupe des directives représentant une extension d'un fournisseur d'autorisation de base qui pourra être référencée à l'aide de l'alias spécifié
AuthzSendForbiddenOnFailure On|Off | Off | dh | B
Envoie '403 FORBIDDEN' au lieu de '401 UNAUTHORIZED' si l'authentification réussit et si l'autorisation a été refusée.
BalancerGrowth # | 5 | sv | E
Nombre de membres supplémentaires pouvant être ajoutés après la configuration initiale
BalancerInherit On|Off | On | sv | E
Héritage des membres du groupes de répartition de charge du mandataire définis au niveau du serveur principal
BalancerMember [balancerurl] url [clé=valeur [clé=valeur ...]] |  | d | E
Ajoute un membre à un groupe de répartition de charge
BalancerPersist On|Off | Off | sv | E
Tente de conserver les changements effectués par le gestionnaire de répartition de charge après un redémarrage du serveur.
BrotliAlterETag AddSuffix|NoChange|Remove | AddSuffix | sv | E
How the outgoing ETag header should be modified during compression
BrotliCompressionMaxInputBlock value |  | sv | E
Maximum input block size
BrotliCompressionQuality value | 5 | sv | E
Compression quality
BrotliCompressionWindow value | 18 | sv | E
Brotli sliding compression window size
BrotliFilterNote [type] notename |  | sv | E
Places the compression ratio in a note for logging
BrowserMatch regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ... |  | svdh | B
Définit des variables d'environnement en fonction du contenu de l'en-tête HTTP User-Agent
BrowserMatchNoCase regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ... |  | svdh | B
Définit des variables d'environnement en fonction du contenu de l'en-tête HTTP User-Agent sans tenir compte de la casse
BufferedLogs On|Off | Off | s | B
Enregistre les entrées du journal dans un tampon en mémoire avant de les écrire sur disque
BufferSize entier | 131072 | svdh | E
Taille maximale en octets du filtre par tampon
CacheDefaultExpire secondes | 3600 (une heure) | svdh | E
La durée par défaut de mise en cache d'un document lorsqu'aucune date d'expiration n'a été spécifiée.
CacheDetailHeader on|off | off | svdh | E
Ajoute un en-tête X-Cache-Detail à la réponse.
CacheDirLength longueur | 2 | sv | E
Le nombre de caractères des noms des sous-répertoires
CacheDirLevels niveaux | 2 | sv | E
Le nombre de niveaux de sous-répertoires que comportera le cache.
CacheDisable chaîne-url | on |  | svdh | E
Désactive la mise en cache des URLs spécifiées
CacheEnable type de cache [chaîne URL] |  | svd | E
Active la mise en cache des URLs spécifiées en utilisant le gestionnaire de stockage précisé
CacheFile chemin fichier [chemin fichier] ... |  | s | X
Met en cache une liste de gestionnaires de fichiers au démarrage
CacheHeader on|off | off | svdh | E
Ajoute un en-tête X-Cache à la réponse.
CacheIgnoreCacheControl On|Off | Off | sv | E
Ignore les en-têtes de requête enjoignant de ne pas servir le contenu au client depuis le cache
CacheIgnoreHeaders en-tête [en-tête] ... | None | sv | E
Ne pas stocker le(s) en-tête(s) spécifié(s) dans le cache.
CacheIgnoreNoLastMod On|Off | Off | svdh | E
Ignore le fait qu'une réponse ne possède pas d'en-tête Last Modified.
CacheIgnoreQueryString On|Off | Off | sv | E
Ignore la chaîne de paramètres lors de la mise en cache
CacheIgnoreURLSessionIdentifiers identifiant [identifiant] ... | None | sv | E
Ignore les identifiants de session définis encodés dans l'URL lors de la mise en cache
CacheKeyBaseURL URL | http://example.com | sv | E
Remplace l'URL de base des clés du cache mandatées en inverse
CacheLastModifiedFactor flottant | 0.1 | svdh | E
Le facteur utilisé pour générer une date d'expiration en fonction de la date de dernière modification.
CacheLock on|off | off | sv | E
Active la protection contre les tempêtes de requêtes.
CacheLockMaxAge entier | 5 | sv | E
Définit la durée de vie maximale d'un verrou de cache.
CacheLockPath répertoire | /tmp/mod_cache-lock + | sv | E
Définit le répertoire des verrous.
CacheMaxExpire secondes | 86400 (une journée) + | svdh | E
La durée maximale en secondes de mise en cache d'un document
CacheMaxFileSize octets | 1000000 | svdh | E
>La taille maximale (en octets) d'un document pour pouvoir être stocké dans le cache
CacheMinExpire secondes | 0 | svdh | E
La durée minimale en secondes de mise en cache d'un document
CacheMinFileSize octets | 1 | svdh | E
La taille minimale (en octets) d'un document pour pouvoir être stocké dans le cache
CacheNegotiatedDocs On|Off | Off | sv | B
Permet la mise en cache au niveau des serveurs mandataires des documents dont le contenu a été négocié
CacheQuickHandler on|off | on | sv | E
Exécute le cache à partir d'un gestionnaire rapide.
CacheReadSize octets | 0 | svdh | E
La quantité minimale (en octets) de données à lire et à mettre en cache avant de les envoyer au client
CacheReadTime millisecondes | 0 | svdh | E
Le temps minimum (en millisecondes) qui doit s'écouler avant d'envoyer les données au client
CacheRoot répertoire |  | sv | E
La racine du répertoire dans lequel les fichiers du cache seront stockés
CacheSocache type[:args] |  | sv | E
Implémentation du cache d'objets partagés à utiliser
CacheSocacheMaxSize octets | 102400 | svdh | E
La taille maximale d'une entrée pouvant être placée dans le cache
CacheSocacheMaxTime secondes | 86400 | svdh | E
La durée maximale de stockage d'un document dans le cache avant péremption
CacheSocacheMinTime seconds | 600 | svdh | E
La durée minimale de stockage d'un document dans le cache
CacheSocacheReadSize octets | 0 | svdh | E
La quantité minimale de données du document à lire et mettre en cache avant envoi au client
CacheSocacheReadTime millisecondes | 0 | svdh | E
La durée minimale de lecture avant l'envoi des données
CacheStaleOnError on|off | on | svdh | E
Sert du contenu non à jour à la place de réponses 5xx.
CacheStoreExpired On|Off | Off | svdh | E
Tente de mettre en cache les réponses que le serveur considère comme arrivées à expiration
CacheStoreNoStore On|Off | Off | svdh | E
Tente de mettre en cache les requêtes ou réponses dont l'entête Cache-Control: a pour valeur no-store.
CacheStorePrivate On|Off | Off | svdh | E
Tente de mettre en cache des réponses que le serveur a marquées comme privées
CGIDScriptTimeout time[s|ms] |  | svdh | B
Durée maximale d'attente de la prochaine sortie du programme CGI
CGIMapExtension chemin CGI .extension |  | dh | C
Technique permettant de localiser l'interpréteur des scripts CGI
CGIPassAuth On|Off | Off | dh | C
Active la transmission d'en-têtes d'autorisation HTTP aux scripts en tant que variables CGI
CGIVar variable rule |  | dh | C
Contrôle la manière dont certaines variables CGI sont définies
CharsetDefault jeu de caractères |  | svdh | E
Jeu de caractère vers lequel la traduction doit s'effectuer
CharsetOptions option [option] ... | ImplicitAdd | svdh | E
Précise les détails de la traduction du jeu de caractères
CharsetSourceEnc jeu de caractères |  | svdh | E
Jeu de caractères source des fichiers
CheckCaseOnly on|off | Off | svdh | E
Limite l'action du module aux corrections de majuscules
CheckSpelling on|off | Off | svdh | E
Active le module de correction
ChrootDir chemin-répertoire |  | s | B
Répertoire dans lequel Apache doit se positionner au démarrage après avoir effectué un chroot(8).
ContentDigest On|Off | Off | svdh | C
Active la génération d'un en-tête Content-MD5 dans la réponse HTTP
CookieDomain domaine |  | svdh | E
Le domaine auquel le cookie traceur s'applique
CookieExpires durée |  | svdh | E
Durée avant expiration du cookie traceur
CookieName symbole | Apache | svdh | E
Nom du cookie traceur
CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965 | Netscape | svdh | E
Format du champ d'en-tête cookie
CookieTracking on|off | off | svdh | E
Active le cookie traceur
CoreDumpDirectory répertoire |  | s | M
Le répertoire dans lequel le serveur HTTP Apache va tenter de se positionner avant d'effectuer un vidage mémoire
CustomLog fichier|pipe format|alias [env=[!]variable-environnement| expr=expression] |  | sv | B
Définit le nom et le format du fichier journal
Dav On|Off|nom fournisseur | Off | d | E
Active les méthodes HTTP WebDAV
DavDepthInfinity on|off | off | svd | E
Autorise les requêtes PROPFIND avec en-tête Depth: Infinity
DavGenericLockDB chemin fichier |  | svd | E
Chemin de la base de données des verrous DAV
DavLockDB chemin fichier |  | sv | E
Chemin de la base de données des verrous DAV
DavMinTimeout secondes | 0 | svd | E
Durée minimale pendant laquelle le serveur maintient un verrou sur une ressource DAV
DBDExptime durée en secondes | 300 | sv | E
Durée de vie des connexions inactives
DBDInitSQL "instruction SQL" |  | sv | E
Exécute une instruction SQL après connexion à une base de données
DBDKeep nombre | 2 | sv | E
Nombre maximum de connexions maintenues
DBDMax nombre | 10 | sv | E
Nombre maximum de connexions
DBDMin nombre | 1 | sv | E
Nombre minimum de connexions
DBDParams param1=valeur1[,param2=valeur2] |  | sv | E
Paramètres de la connexion à la base de données
DBDPersist On|Off |  | sv | E
Utiliser ou non des connexions persistentes
DBDPrepareSQL "requête SQL" étiquette |  | sv | E
Définit une requête SQL préparée
DBDriver nom |  | sv | E
Spécifie un pilote SQL
DefaultIcon chemin URL |  | svdh | B
Icône à afficher par défaut lorsqu'aucun icône spécifique n'est précisé
DefaultLanguage symbole-langue |  | svdh | B
Définit un symbole de langue par défaut à affecter au champ d'en-tête Content-Language pour toutes les ressources dans le contexte courant auxquelles aucun symbole de langue n'a été associé.
DefaultRuntimeDir chemin-répertoire | DEFAULT_REL_RUNTIME + | s | C
Répertoire de base des fichiers créés au cours de l'exécution du serveur
DefaultType type média|none | none | svdh | C
Les seuls effets de cette directive sont des émissions d'avertissements si sa valeur est différente de none. Dans les versions précédentes, DefaultType permettait de spécifier un type de média à assigner par défaut au contenu d'une réponse pour lequel aucun autre type de média n'avait été trouvé.
Define nom-paramètre [valeur-paramètre] |  | svd | C
Permet de définir une variable
DeflateBufferSize valeur | 8096 | sv | E
Taille du fragment que zlib devra comprimer en une seule fois
DeflateCompressionLevel valeur |  | sv | E
Le niveau de compression que nous appliquons à la sortie
DeflateFilterNote [type] nom de la note |  | sv | E
Enregistre le taux de compression sous la forme d'une note à des fins de journalisation
DeflateInflateLimitRequestBodyvalue |  | svdh | E
Taille maximale des corps de requête décompressés
DeflateInflateRatioBurst value |  | svdh | E
Nombre maximal de fois que le ratio de décompression d'un corps de requête peut être dépassé
DeflateInflateRatioLimit value |  | svdh | E
Ratio de décompression maximum pour les corps de requêtes
DeflateMemLevel valeur | 9 | sv | E
La quantité de mémoire utilisable par zlib pour la compression
DeflateWindowSize valeur | 15 | sv | E
Taille de la fenêtre de compression zlib
Deny from all|hôte|env=[!]variable d'environnement [hôte|env=[!]variable d'environnement] ... |  | dh | E
Définit quels hôtes ne sont pas autorisés à accéder au serveur
<Directory chemin répertoire> ... </Directory> |  | sv | C
Regroupe un ensemble de directives qui ne s'appliquent qu'au répertoire concerné du système de fichiers, à ses sous-répertoires, et à leur contenu.
DirectoryCheckHandler On|Off | Off | svdh | B
Définit la réponse de ce module lorsqu'un autre gestionnaire est utilisé
DirectoryIndex disabled | url locale [url locale] ... | index.html | svdh | B
Liste des fichiers ressources à rechercher lorsque le client envoie une requête pour un répertoire
DirectoryIndexRedirect on | off | permanent | temp | seeother | 3xx-code | off | svdh | B
Définit une redirection externe pour les index de répertoires.
<DirectoryMatch regex> ... </DirectoryMatch> |  | sv | C
Regroupe des directives qui s'appliquent au contenu de répertoires du système de fichiers correspondant à une expression rationnelle
DirectorySlash On|Off | On | svdh | B
Activation/Désactivation de la redirection "slash de fin"
DocumentRoot chemin répertoire | "/usr/local/apache/ + | sv | C
Racine principale de l'arborescence des documents visible depuis Internet
DTracePrivileges On|Off | Off | s | X
Détermine si les privilèges requis par dtrace sont activés.
DumpIOInput On|Off | Off | s | E
Enregistre toutes les entrées dans le journal des erreurs
DumpIOOutput On|Off | Off | s | E
Enregistre toutes les sorties dans le journal des erreurs
<Else> ... </Else> |  | svdh | C
Contient des directives qui ne s'appliquent que si la condition correspondant à la section <If> ou <ElseIf> précédente n'est pas satisfaite par la requête à l'exécution
<ElseIf expression> ... </ElseIf> |  | svdh | C
Contient des directives qui ne s'appliquent que si la condition correspondante est satisfaite par une requête à l'exécution, alors que la condition correspondant à la section <If> ou <ElseIf> précédente ne l'était pas.
EnableExceptionHook On|Off | Off | s | M
Active un hook ("point d'accrochage logiciel") qui exécute des gestionnaires d'exception après un crash
EnableMMAP On|Off | On | svdh | C
Utilise la projection en mémoire (Memory-Mapping) pour lire les fichiers pendant qu'ils sont servis
EnableSendfile On|Off | Off | svdh | C
Utilise le support sendfile du noyau pour servir les fichiers aux clients
Error message |  | svdh | C
Interrompt la lecture de la configuration avec un message d'erreur personnalisé
ErrorDocument code erreur document |  | svdh | C
Document que le serveur renvoie au client en cas d'erreur
ErrorLog file-path|syslog[:[facility][:tag]] | logs/error_log (Uni + | sv | C
Définition du chemin du journal des erreurs
ErrorLogFormat [connection|request] format |  | sv | C
Spécification du format des entrées du journal des erreurs
Example |  | svdh | X
Directive de démonstration pour illustrer l'API des modules Apache
ExpiresActive On|Off | Off | svdh | E
Active la génération d'en-têtes Expires
ExpiresByType type MIME <code>secondes |  | svdh | E
Définition de la valeur de l'en-tête Expires en fonction du type MIME
ExpiresDefault <code>secondes |  | svdh | E
Mode de calcul par défaut de la date d'expiration
ExtendedStatus On|Off | Off | s | C
Extrait des informations d'état étendues pour chaque requête
ExtFilterDefine nom_filtre paramètres |  | s | E
Définit un filtre externe
ExtFilterOptions option [option] ... | NoLogStderr | d | E
Configure les options de mod_ext_filter
FallbackResource disabled | url-locale |  | svdh | B
Définit une URL par défaut pour les requêtes qui ne ciblent aucun fichier
FileETag composant ... | MTime Size | svdh | C
Caractéristiques de fichier utilisées lors de la génération de l'en-tête de réponse HTTP ETag pour les fichiers statiques
<Files nom fichier> ... </Files> |  | svdh | C
Contient des directives qui s'appliquent aux fichiers précisés
<FilesMatch expression rationnelle> ... </FilesMatch> |  | svdh | C
Contient des directives qui s'appliquent à des fichiers spécifiés sous la forme d'expressions rationnelles
FilterChain [+=-@!]nom_filtre ... |  | svdh | B
Configure la chaîne de filtrage
FilterDeclare nom_filtre [type] |  | svdh | B
Déclare un filtre intelligent
FilterProtocol nom_filtre [nom_fournisseur] drapeaux_protocole |  | svdh | B
Vérifie le respect du protocole HTTP
FilterProvider nom_filtre nom_fournisseur expression |  | svdh | B
Enregistre un filtre de contenu
FilterTrace nom_filtre niveau |  | svd | B
Obtention d'informations de débogage/diagnostique en provenance de mod_filter
ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback] | Prefer | svdh | B
Action à entreprendre si un document acceptable unique n'est pas trouvé
ForceType type médium|None |  | dh | C
Force le type de médium spécifié dans le champ d'en-tête HTTP Content-Type pour les fichiers correspondants
ForensicLog nom-fichier|pipe |  | sv | E
Définit le nom de fichier du journal légal
GlobalLogfile|pipe format|nickname [env=[!]environment-variable| expr=expression] |  | s | B
Définit le nom et le format du fichier journal
GprofDir /tmp/gprof/|/tmp/gprof/% |  | sv | C
Répertoire dans lequel écrire les données de profiling gmon.out.
GracefulShutdownTimeout seconds | 0 | s | M
Spécifie le délai maximum après lequel le serveur va s'arrêter dans le cas d'un arrêt "en douceur"
Group groupe unix | #-1 | s | B
Groupe sous lequel le serveur va traiter les requêtes
H2CopyFiles on|off | off | svdh | E
Determine file handling in responses
H2Direct on|off | on for h2c, off for + | sv | E
H2 Direct Protocol Switch
H2EarlyHints on|off | off | sv | E
Determine sending of 103 status codes
H2MaxSessionStreams n | 100 | sv | E
Maximum number of active streams per HTTP/2 session.
H2MaxWorkerIdleSeconds n | 600 | s | E
Maximum number of seconds h2 workers remain idle until shut down.
H2MaxWorkers n |  | s | E
Maximum number of worker threads to use per child process.
H2MinWorkers n |  | s | E
Minimal number of worker threads to use per child process.
H2ModernTLSOnly on|off | on | sv | E
Require HTTP/2 connections to be "modern TLS" only
H2Push on|off | on | sv | E
H2 Server Push Switch
H2PushDiarySize n | 256 | sv | E
H2 Server Push Diary Size
H2PushPriority mime-type [after|before|interleaved] [weight] | * After 16 | sv | E
H2 Server Push Priority
H2PushResource [add] path [critical] |  | svdh | E
Declares resources for early pushing to the client
H2SerializeHeaders on|off | off | sv | E
Serialize Request/Response Processing Switch
H2StreamMaxMemSize bytes | 65536 | sv | E
Maximum amount of output data buffered per stream.
H2TLSCoolDownSecs seconds | 1 | sv | E
-
H2TLSWarmUpSize amount | 1048576 | sv | E
-
H2Upgrade on|off | on for h2c, off for + | sv | E
H2 Upgrade Protocol Switch
H2WindowSize bytes | 65535 | sv | E
Size of Stream Window for upstream data.
Header [condition] add|append|echo|edit|edit*|merge|set|setifempty|unset|note en-tête [[expr=]valeur [remplacement] [early|env=[!]variable|expr=expression]] |  | svdh | E
Configure les en-têtes d'une réponse HTTP
HeaderName nom fichier |  | svdh | B
Nom du fichier qui sera inséré au début de la page contenant l'index
HeartbeatAddress addr:port |  | s | X
Adresse multicast à laquelle envoyer les requêtes heartbeat
HeartbeatListenaddr:port |  | s | X
Adresse multicast d'écoute des requêtes entrantes heartbeat
HeartbeatMaxServers nombre-de-serveurs | 10 | s | X
Spécifie le nombre maximal de serveurs qui pourront envoyer des requêtes heartbeat à ce serveur.
HeartbeatStorage chemin fichier | logs/hb.dat | s | X
Chemin vers le stockage des données heartbeat
HeartbeatStorage chemin-fichier | logs/hb.dat | s | X
Indique le chemin permettant de lire les données heartbeat
HostnameLookups On|Off|Double | Off | svd | C
Active la recherche DNS sur les adresses IP des clients
HttpProtocolOptions [Strict|Unsafe] [RegisteredMethods|LenientMethods] [Allow0.9|Require1.0] | Strict LenientMetho + | sv | C
Modifie les contraintes sur les messages des requêtes HTTP
IdentityCheck On|Off | Off | svd | E
Active la journalisation de l'identité RFC 1413 de l'utilisateur distant
IdentityCheckTimeout secondes | 30 | svd | E
Détermine le délai d'attente pour les requêtes ident
<If expression> ... </If> |  | svdh | C
Contient des directives qui ne s'appliquent que si une condition est satisfaite au cours du traitement d'une requête
<IfDefine [!]paramètre> ... </IfDefine> |  | svdh | C
Contient des directives qui ne s'appliqueront que si un test retourne "vrai" au démarrage du serveur
<IfModule [!]fichier module|identificateur module> ... </IfModule> |  | svdh | C
Contient des directives qui ne s'appliquent qu'en fonction de la présence ou de l'absence d'un module spécifique
<IfVersion [[!]operator] version> ... </IfVersion> |  | svdh | E
contains version dependent configuration
ImapBase map|referer|URL | http://nom_serveur/ + | svdh | B
Valeur par défaut de la directive base des fichiers imagemap
ImapDefault error|nocontent|map|referer|URL | nocontent | svdh | B
Action à entreprendre par défaut lorsqu'un fichier imagemap est invoqué avec des coordonnées qui ne correspondent à aucune cible
ImapMenu none|formatted|semiformatted|unformatted | formatted | svdh | B
Action à entreprendre si aucune coordonnée n'est fournie lorsqu'on invoque un fichier imagemap
Include chemin-fichier|chemin-répertoire|wildcard |  | svd | C
Inclut d'autres fichiers de configuration dans un des fichiers de configuration du serveur
IncludeOptional file-path|directory-path|wildcard |  | svd | C
Inclusion de fichiers dans le fichier de configuration
IndexHeadInsert "marque ..." |  | svdh | B
Insère du texte dans la section HEAD de la page d'index.
IndexIgnore fichier [fichier] ... | "." | svdh | B
Ajouts à la liste des fichiers à cacher lors de l'affichage de l'index d'un répertoire
IndexIgnoreReset ON|OFF |  | svdh | B
Vide la liste des fichiers à cacher lors de l'affichage du contenu d'un répertoire
IndexOptions [+|-]option [[+|-]option] ... |  | svdh | B
Diverses options de configuration pour l'indexation d'un répertoire
IndexOrderDefault Ascending|Descending Name|Date|Size|Description | Ascending Name | svdh | B
Définit l'ordre d'affichage par défaut d'un index de répertoire
IndexStyleSheet chemin-url |  | svdh | B
Ajoute une feuille de style CSS à l'index du répertoire
InputSed commande-sed |  | dh |
Commande sed à exécuter pour le filtrage des données d'une requête (en général des données POST)
ISAPIAppendLogToErrors on|off | off | svdh | B
Enregistrement des requêtes HSE_APPEND_LOG_PARAMETER de la part des extensions ISAPI dans le journal des erreurs
ISAPIAppendLogToQuery on|off | on | svdh | B
Enregistre les requêtes HSE_APPEND_LOG_PARAMETER de la part des extensions ISAPI dans la partie arguments de la requête
ISAPICacheFile chemin-fichier [chemin-fichier] ... |  | sv | B
Fichiers .dll ISAPI devant être chargés au démarrage
ISAPIFakeAsync on|off | off | svdh | B
Emulation du support des entrées/sorties asynchrones pour les appels ISAPI
ISAPILogNotSupported on|off | off | svdh | B
Journalisation des demandes de fonctionnalités non supportées de la part des extensions ISAPI
ISAPIReadAheadBuffer taille | 49152 | svdh | B
Taille du tampon de lecture anticipée envoyé aux extensions ISAPI
KeepAlive On|Off | On | sv | C
Active les connexions HTTP persistantes
KeepAliveTimeout nombre[ms] | 5 | sv | C
Durée pendant laquelle le serveur va attendre une requête avant de fermer une connexion persistante
KeptBodySize taille maximale en octets | 0 | d | B
Conserve le corps de la requête à concurrence de la taille maximale spécifiée, pour une utilisation éventuelle par des filtres comme mod_include.
LanguagePriority langage-MIME [langage-MIME] ... |  | svdh | B
L'ordre de priorité des variantes de langages pour les cas où le client n'a pas formulé de préférences
LDAPCacheEntries nombre | 1024 | s | E
Nombre maximum d'entrées dans le cache LDAP primaire
LDAPCacheTTL secondes | 600 | s | E
Durée pendant laquelle les entrées du cache restent valides.
LDAPConnectionPoolTTL n | -1 | sv | E
Désactive les connexions d'arrière-plan qui sont restées inactives trop longtemps au sein du jeu de connexions.
LDAPConnectionTimeout secondes |  | s | E
Spécifie le délai d'attente en secondes de la socket de connexion
LDAPLibraryDebug 7 |  | s | E
Active le débogage dans le SDK LDAP
LDAPOpCacheEntries nombre | 1024 | s | E
Nombre d'entrées utilisées pour mettre en cache les opérations de comparaison LDAP
LDAPOpCacheTTL secondes | 600 | s | E
Durée pendant laquelle les entrées du cache d'opérations restent valides
LDAPReferralHopLimit nombre |  | dh | E
Le nombre maximum de redirections vers des serveurs alternatifs (referrals) avant l'abandon de la requête LDAP.
LDAPReferrals On|Off|default | On | dh | E
Active la redirection vers des serveurs alternatifs au cours des requêtes vers le serveur LDAP.
LDAPRetries nombre d'essais | 3 | s | E
Définit le nombre maximum de tentatives de connexions au serveur LDAP.
LDAPRetryDelay secondes | 0 | s | E
Définit le temps d'attente avant un autre essai de connexion au serveur LDAP.
LDAPSharedCacheFile chemin/fichier |  | s | E
Définit le fichier du cache en mémoire partagée
LDAPSharedCacheSize octets | 500000 | s | E
Taille en octets du cache en mémoire partagée
LDAPTimeout secondes | 60 | s | E
Spécifie le délai d'attente pour les opérations de recherche et d'identification LDAP en secondes
LDAPTrustedClientCert type chemin/nom-fichier/alias [mot de passe] |  | svdh | E
Définit le nom de fichier contenant un certificat client ou un alias renvoyant vers un certificat client spécifique à une connexion. Tous les SDK LDAP ne supportent pas les certificats clients par connexion.
LDAPTrustedGlobalCert type chemin/nom-fichier [mot de passe] |  | s | E
Définit le nom de fichier ou la base de données contenant les Autorités de Certification de confiance globales ou les certificats clients globaux
LDAPTrustedMode type |  | sv | E
Spécifie le mode (SSL ou TLS) à utiliser lors de la connexion à un serveur LDAP.
LDAPVerifyServerCert On|Off | On | s | E
Force la vérification du certificat du serveur
<Limit méthode [méthode] ... > ... </Limit> |  | dh | C
Limite les contrôles d'accès que la section contient à certaines méthodes HTTP
<LimitExcept méthode [méthode] ... > ... </LimitExcept> |  | dh | C
Applique les contrôles d'accès à toutes les méthodes HTTP, sauf celles qui sont spécifiées
LimitInternalRecursion nombre [nombre] | 10 | sv | C
Détermine le nombre maximal de redirections internes et de sous-requêtes imbriquées
LimitRequestBody octets | 0 | svdh | C
limite la taille maximale du corps de la requête HTTP envoyée par le client
LimitRequestFields nombre | 100 | sv | C
Limite le nombre de champs d'en-tête autorisés dans une requête HTTP
LimitRequestFieldSize octets | 8190 | sv | C
Dédinit la taille maximale autorisée d'un en-tête de requête HTTP
LimitRequestLine octets | 8190 | sv | C
Définit la taille maximale d'une ligne de requête HTTP
LimitXMLRequestBody octets | 1000000 | svdh | C
Définit la taille maximale du corps d'une requête au format XML
Listen [adresse IP:]numéro port [protocole] |  | s | M
Les adresses IP et ports sur lesquels le serveur écoute
ListenBacklog backlog |  | s | M
Longueur maximale de la liste d'attente des connexions
ListenCoresBucketsRatio ratio | 0 (disabled) | s | M
Rapport entre le nombre de coeurs de processeur activés et le nombre de segments d'écoute
LoadFile nom-fichier [nom-fichier] ... |  | sv | E
Liaison du fichier objet ou de la bibliothèque spécifié
LoadModule module nom-fichier |  | sv | E
Liaison avec le serveur du fichier objet ou de la bibliothèque spécifié, et ajout de ce dernier à la liste des modules actifs
<Location chemin URL|URL> ... </Location> |  | sv | C
N'applique les directives contenues qu'aux URLs spécifiées
<LocationMatch regex> ... </LocationMatch> |  | sv | C
N'applique les directives contenues qu'aux URLs correspondant à une expression rationnelle
LogFormat format|alias [alias] | "%h %l %u %t \"%r\" + | sv | B
Décrit un format utilisable dans un fichier journal
LogIOTrackTTFB ON|OFF | OFF | svdh | E
Permet d'enregistrer le délai avant le premier octet (time to first byte - TTFB)
LogLevel [module:]niveau [module:niveau] ... | warn | svd | C
Contrôle la verbosité du journal des erreurs
LogMessage message [hook=hook] [expr=expression] |  | d | X
Enregistre des messages personnalisés dans le journal des erreurs
LuaAuthzProvider provider_name /path/to/lua/script.lua function_name |  | s | X
Branche une fonction fournisseur d'autorisation dans mod_authz_core
LuaCodeCache stat|forever|never | stat | svdh | X
Configure le cache de code compilé.
LuaHookAccessChecker /chemin/vers/lua/script.lua hook_function_name [early|late] |  | svdh | X
Fournit un point d'entrée pour la phase access_checker du traitement de la requête
LuaHookAuthChecker /chemin/vers/lua/script.lua hook_function_name [early|late] |  | svdh | X
Fournit un point d'entrée pour la phase auth_checker du traitement de la requête
LuaHookCheckUserID /chemin/vers/lua/script.lua hook_function_name [early|late] |  | svdh | X
Fournit un point d'entrée pour la phase check_user_id du traitement de la requête
LuaHookFixups /chemin/vers/lua/script.lua hook_function_name |  | svdh | X
Fournit un point d'entrée pour la phase de correction du traitement de la requête
LuaHookInsertFilter /chemin/vers/lua/script.lua hook_function_name |  | svdh | X
Fournit un point d'entrée pour la phase insert_filter du traitement de la requête
LuaHookLog /path/to/lua/script.lua log_function_name |  | svdh | X
Permet une insertion dans la phase de journalisation du traitement d'une requête
LuaHookMapToStorage /chemin/vers/lua/script.lua hook_function_name |  | svdh | X
Fournit un point d'entrée pour la phase map_to_storage du traitement de la requête
LuaHookTranslateName /chemin/vers/lua/script.lua nom_fonction_hook [early|late] |  | sv | X
Fournit un point d'entrée à la phase du nom de traduction du traitement de la requête
LuaHookTypeChecker /chemin/vers/lua/script.lua hook_function_name |  | svdh | X
Fournit un point d'entrée pour la phase type_checker du traitement de la requête
LuaInherit none|parent-first|parent-last | parent-first | svdh | X
Contrôle la manière dont les sections de configuration parentes sont fusionnées dans les enfants
LuaInputFilter filter_name /path/to/lua/script.lua function_name |  | s | X
Fournit une fonction Lua pour le filtrage en entrée
LuaMapHandler modele-uri /chemin/vers/lua/script.lua [nom-fonction] |  | svdh | X
Met en correspondance un chemin avec un gestionnaire lua
LuaOutputFilter filter_name /path/to/lua/script.lua function_name |  | s | X
Fournit une fonction Lua pour le filtrage de contenu en sortie
LuaPackageCPath /chemin/vers/include/?.soa |  | svdh | X
Ajoute un répertoire au package.cpath de lua
LuaPackagePath /chemin/vers/include/?.lua |  | svdh | X
Ajoute un répertoire au package.path de lua
LuaQuickHandler /path/to/script.lua hook_function_name |  | svdh | X
Fournit un point d'entrée pour la gestion rapide du traitement de la requête
LuaRoot /chemin/vers/un/répertoire |  | svdh | X
Spécifie le chemin de base pour la résolution des chemins relatifs dans les directives de mod_lua
LuaScope once|request|conn|thread|server [min] [max] | once | svdh | X
Une valeur parmi once, request, conn, thread -- la valeur par défaut est once
<Macro nom [par1 .. parN]> ... </Macro> |  | svd | B
Définition d'une macro dans un fichier de configuration
MaxConnectionsPerChild number | 0 | s | M
Limite le nombre de connexions qu'un processus enfant va traiter au cours de son fonctionnement
MaxKeepAliveRequests nombre | 100 | sv | C
Nombre de requêtes permises pour une connexion persistante
MaxMemFree KOctets | 2048 | s | M
Quantité maximale de mémoire que l'allocateur principal est autorisé à conserver sans appeler free()
MaxRangeOverlaps default | unlimited | none | nombre de chevauchements | 20 | svd | C
Nombre de chevauchements de segments de données autorisé (par exemple 100-200,150-300) avant le renvoi de la ressource complète
MaxRangeReversals default | unlimited | none | nombre d'inversions | 20 | svd | C
Nombre d'inversions d'ordre autorisé dans la spécification des segments de données (par exemple 100-200,50-70) avant le renvoi de la ressource complète
MaxRanges default | unlimited | none | nombre de segments | 200 | svd | C
Nombre de segments de données autorisé avant le renvoi de l'intégralité de la ressource
MaxRequestWorkers nombre |  | s | M
Nombre maximum de connexions pouvant être traitées simultanément
MaxSpareServers nombre | 10 | s | M
Nombre maximum de processus serveurs enfants inactifs
MaxSpareThreads nombre |  | s | M
Nombre maximum de threads inactifs
MaxThreads nombre | 2048 | s | M
Définit le nombre maximum de threads esclaves
MDBaseServer on|off | off | s | E
Control if base server may be managed or only virtual hosts.
MDCAChallenges name [ name ... ] | tls-sni-01 http-01 | s | E
Type of ACME challenge used to prove domain ownership.
MDCertificateAgreement url-of-terms-of-service |  | s | E
The URL of the Terms-of-Service document, that the CA server requires you to accept.
MDCertificateAuthority url | https://acme-v01.ap + | s | E
The URL of the ACME Certificate Authority service.
MDCertificateProtocol protocol | ACME | s | E
The protocol to use with the Certificate Authority.
MDDriveMode always|auto|manual | auto | s | E
Control when it is allowed to obtain/renew certificates.
MDHttpProxy url |  | s | E
Define a proxy for outgoing connections.
MDMember hostname |  | s | E
Additional hostname for the managed domain.
MDMembers auto|manual | auto | s | E
Control if the alias domain names are automatically added.
MDMustStaple on|off | off | s | E
Control if new certificates carry the OCSP Must Staple flag.
MDNotifyCmd path |  | s | E
Run a program when Managed Domain are ready.
MDomain dns-name [ other-dns-name... ] [auto|manual] |  | s | E
Define list of domain names that belong to one group.
<MDomainSet dns-name [ other-dns-name... ]>...</MDomainSet> |  | s | E
Container for directives applied to the same managed domains.
MDPortMap map1 [ map2 ] | 80:80 443:443 | s | E
Map external to internal ports for domain ownership verification.
MDPrivateKeys type [ params... ] | RSA 2048 | s | E
Set type and size of the private keys generated.
MDRenewWindow duration | 33% | s | E
Control when a certificate will be renewed.
MDRequireHttps off|temporary|permanent | off | s | E
Redirects http: traffic to https: for Managed Domains.
MDStoreDir path | md | s | E
Path on the local file system to store the Managed Domains data.
MemcacheConnTTL num[units] | 15s | sv | E
Durée de conservation des connexions inactives
MergeTrailers [on|off] | off | sv | C
Détermine si les données supplémentaires (trailers) sont fusionnées avec les en-têtes
MetaDir répertoire | .web | svdh | E
Le nom du répertoire où trouver les fichiers de métainformations dans le style du CERN
MetaFiles on|off | off | svdh | E
Active le traitement des métafichiers du CERN
MetaSuffix suffixe | .meta | svdh | E
Suffixe du fichier contenant les métainformations dans le style du CERN
MimeMagicFile chemin-fichier |  | sv | E
Active la détermination du type MIME en se basant sur le contenu du fichier et en utilisant le fichier magique spécifié
MinSpareServers nombre | 5 | s | M
Nombre minimum de processus serveurs enfants inactifs
MinSpareThreads nombre |  | s | M
Nombre minimum de threads inactifs qui seront disponibles pour pouvoir traiter les pics de requêtes
MMapFile chemin fichier [chemin fichier] ... |  | s | X
Charge au démarrage une liste de fichiers en mémoire
ModemStandard V.21|V.26bis|V.32|V.34|V.92 |  | d | X
Standard de modem à simuler
ModMimeUsePathInfo On|Off | Off | d | B
Indique à mod_mime de traiter les éléments de path_info en tant que parties du nom de fichier
MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters] | NegotiatedOnly | svdh | B
Les types de fichiers qui seront inclus lors d'une recherche de correspondance de fichier avec les vues multiples (MultiViews)
Mutex mécanisme [default|nom-mutex] ... [OmitPID] | default | s | C
Définit les mécanismes de mutex et le repertoire du fichier verrou pour tous les mutex ou seulement les mutex spécifiés
NameVirtualHost adresse[:port] |  | s | C
OBSOLETE : Définit une adresse IP pour les serveurs virtuels à base de nom
NoProxy domaine [domaine] ... |  | sv | E
Serveurs, domaines ou réseaux auquels on se connectera directement
NWSSLTrustedCerts nom-fichier [nom-fichier] ... |  | s | B
Liste de certificats clients supplémentaires
NWSSLUpgradeable [adresse-IP:]num-port |  | s | B
Permet de promouvoir une connexion non SSL au statut de connexion SSL à la demande
Options [+|-]option [[+|-]option] ... | FollowSymlinks | svdh | C
Définit les fonctionnalités disponibles pour un répertoire particulier
Order ordre | Deny,Allow | dh | E
Définit le statut d'accès par défaut et l'ordre dans lequel les directives Allow et Deny sont évaluées.
OutputSed commande-sed |  | dh |
Commande sed pour le filtrage des contenus de type réponse
PassEnv var-env [var-env] ... |  | svdh | B
Transmet des variables d'environnement depuis le shell
PidFile nom fichier | logs/httpd.pid | s | M
Ficher dans lequel le serveur enregistre l'identificateur de processus du démon
PrivilegesMode FAST|SECURE|SELECTIVE | FAST | svd | X
Fait un compromis entre d'une part l'efficacité et la vitesse de traitement et d'autre part la sécurité à l'encontre des codes malicieux supportant les privilèges.
Protocol protocole |  | sv | C
Protocole pour une socket d'écoute
ProtocolEcho On|Off | Off | sv | X
Active ou désactive le serveur d'écho
Protocols protocole ... | http/1.1 | sv | C
Protocoles disponibles pour un serveur virtuel ou non
ProtocolsHonorOrder On|Off | On | sv | C
Détermine qui du client ou du serveur détermine l'ordre des protocoles au cours de la négociation de la connexion
<Proxy url-avec-jokers> ...</Proxy> |  | sv | E
Conteneur de directives s'appliquant à des ressources mandatées
ProxyAddHeaders Off|On | On | svd | E
Ajoute des informations à propos du mandataire aux en-têtes X-Forwarded-*
ProxyBadHeader IsError|Ignore|StartBody | IsError | sv | E
Détermine la manière de traiter les lignes d'en-tête incorrectes d'une réponse
ProxyBlock *|terme|serveur|domaine [terme|serveur|domaine] ... |  | sv | E
Termes, serveurs ou domaines bloqués par le mandataire
ProxyDomain Domaine |  | sv | E
Nom de domaine par défaut pour les requêtes mandatées
ProxyErrorOverride On|Off | Off | svd | E
Outrepasser les pages d'erreur pour les contenus mandatés
ProxyExpressDBMFile <chemin> |  | sv | E
Chemin du fichier DBM.
ProxyExpressDBMFile <type> |  | sv | E
Type de fichier DBM.
ProxyExpressEnable [on|off] |  | sv | E
Active la fonctionnalité du module.
ProxyFCGIBackendType FPM|GENERIC | FPM | svdh | E
Spécifie le type de l'application FastCGI d'arrière-plan
ProxyFCGISetEnvIf conditional-expression [!]environment-variable-name [value-expression] |  | svdh | E
Permet d'adapter la valeur des variables envoyées aux serveurs FastCGI
ProxyFtpDirCharset jeu-caractères | ISO-8859-1 | svd | E
Définit le jeu de caractères des listings FTP mandatés
ProxyFtpEscapeWildcards [on|off] |  | svd | E
Les caractères génériques dans les noms de fichiers doivent-ils être échappés lorsqu'ils sont envoyés au serveur FTP ?
ProxyFtpListOnWildcard [on|off] |  | svd | E
Les caractères génériques dans les noms de fichiers demandés doivent-ils déclencher l'affichage d'un listing ?
ProxyHCExpr name {ap_expr expression} |  | sv | E
Creates a named condition expression to use to determine health of the backend based on its response.
ProxyHCTemplate name parameter=setting <...> |  | sv | E
Creates a named template for setting various health check parameters
ProxyHCTPsize <size> |  | s | E
Sets the total server-wide size of the threadpool used for the health check workers.
ProxyHTMLBufSize nb-octets |  | svd | B
Définit l'incrément de la taille du tampon, ainsi que sa taille initiale, pour la mise en tampon des scripts en ligne et des feuilles de style.
ProxyHTMLCharsetOut jeu-de-caractères | * |  | svd | B
Spécifie un jeu de caractères pour la sortie de mod_proxy_html.
ProxyHTMLDocType HTML|XHTML [Legacy] OR ProxyHTMLDocType fpi [SGML|XML] |  | svd | B
Définit une déclaration de type de document HTML ou XHTML.
ProxyHTMLEnable On|Off | Off | svd | B
Permet d'activer/désactiver le filtre proxy_html.
ProxyHTMLEvents attribut [attribut ...] |  | svd | B
Spécifie les attributs à traiter comme des évènements de type scripting.
ProxyHTMLExtended On|Off | Off | svd | B
Détermine si l'on doit corriger les liens dans les scripts en ligne, les feuilles de style et les évènements de type scripting.
ProxyHTMLFixups [lowercase] [dospath] [reset] |  | svd | B
Corrige les erreurs HTML simples.
ProxyHTMLInterp On|Off | Off | svd | B
Active la réinterprétation des règles ProxyHTMLURLMap pour chaque requête.
ProxyHTMLLinks élément attribut [attribut2 ...] |  | svd | B
Spécifie les éléments HTML dont les attributs d'URL doivent être réécrits.
ProxyHTMLMeta On|Off | Off | svd | B
Active ou désactive une préinterprétation supplémentaire des métadonnées dans les sections HTML <head>.
ProxyHTMLStripComments On|Off | Off | svd | B
Détermine si les commentaires HTML doivent être supprimés.
ProxyHTMLURLMap modèle-source modèle-cible [drapeaux] [cond] |  | svd | B
Définit une règle de réécriture des liens HTML
ProxyIOBufferSize octets | 8192 | sv | E
Détermine la taille du tampon interne de transfert de données
<ProxyMatch regex> ...</ProxyMatch> |  | sv | E
Conteneur de directives s'appliquant à des ressources mandatées correspondant à une expression rationnelle
ProxyMaxForwards nombre | -1 | sv | E
Nombre maximum de mandataires à travers lesquelles une requête peut être redirigée
ProxyPass [chemin] !|url [clé=valeur [clé=valeur ...]] [nocanon] [interpolate] [noquery] |  | svd | E
Référencer des serveurs distants depuis l'espace d'URLs du serveur local
ProxyPassInherit On|Off | On | sv | E
Héritage des directives ProxyPass définies au niveau du serveur principal
ProxyPassInterpolateEnv On|Off | Off | svd | E
Active l'interpolation des variables d'environnement dans les configurations de mandataires inverses
ProxyPassMatch [regex] !|url [clé=valeur [clé=valeur ...]] |  | svd | E
Fait correspondre des serveurs distants dans l'espace d'URL du serveur local en utilisant des expressions rationnelles
ProxyPassReverse [chemin] url [interpolate] |  | svd | E
Ajuste l'URL dans les en-têtes de la réponse HTTP envoyée par un serveur mandaté en inverse
ProxyPassReverseCookieDomain domaine-interne domaine-public [interpolate] |  | svd | E
Ajuste la chaîne correspondant au domaine dans les en-têtes Set-Cookie en provenance d'un serveur mandaté
ProxyPassReverseCookiePath chemin-interne chemin-public [interpolate] |  | svd | E
Ajuste la chaîne correspondant au chemin dans les en-têtes Set-Cookie en provenance d'un serveur mandaté
ProxyPreserveHost On|Off | Off | svd | E
Utilise l'en-tête de requête entrante Host pour la requête du mandataire
ProxyReceiveBufferSize octets | 0 | sv | E
Taille du tampon réseau pour les connexions mandatées HTTP et FTP
ProxyRemote comparaison serveur-distant |  | sv | E
Mandataire distant à utiliser pour traiter certaines requêtes
ProxyRemoteMatch regex serveur-distant |  | sv | E
Le mandataire distant à utiliser pour traiter les requêtes correspondant à une expression rationnelle
ProxyRequests On|Off | Off | sv | E
Active la fonctionnalité (standard) de mandataire direct
ProxySCGIInternalRedirect On|Off|Headername | On | svd | E
Active ou désactive les réponses de redirection interne en provenance du serveur cible.
ProxySCGISendfile On|Off|nom-en-tête | Off | svd | E
Active l'évaluation du pseudo en-tête de réponse X-Sendfile
ProxySet url clé=valeur [clé=valeur ...] |  | d | E
Définit différents paramètres relatifs à la répartition de charge des mandataires et aux membres des groupes de répartition de charge
ProxySourceAddress adresse |  | sv | E
Définit l'adresse IP locale pour les connexions mandatées sortantes
ProxyStatus Off|On|Full | Off | sv | E
Affiche l'état du répartiteur de charge du mandataire dans mod_status
ProxyTimeout secondes |  | sv | E
Délai d'attente réseau pour les requêtes mandatées
ProxyVia On|Off|Full|Block | Off | sv | E
Information fournie dans l'en-tête de réponse HTTP Via pour les requêtes mandatées
QualifyRedirectURL ON|OFF | OFF | svd | C
Vérifie si la variable d'environnement REDIRECT_URL est pleinement qualifiée
ReadmeName nom-fichier |  | svdh | B
Nom du fichier dont le contenu sera inséré à la fin de l'index
ReceiveBufferSize octets | 0 | s | M
Taille du tampon TCP en entrée
Redirect [état] [URL-path] URL |  | svdh | B
Envoie une redirection externe demandant au client d'effectuer une autre requête avec une URL différente
RedirectMatch [état] regex URL |  | svdh | B
Envoie une redirection externe faisant appel aux expressions rationnelles pour la mise en correspondance de l'URL courante
RedirectPermanent chemin URL URL |  | svdh | B
Envoie une redirection externe permanente demandant au client d'effectuer une nouvelle requête avec une URL différente
RedirectTemp chemin URL URL |  | svdh | B
Envoie une redirection externe temporaire demandant au client d'effectuer une nouvelle requête avec une URL différente
ReflectorHeader en-tête-entrée [en-tête-sortie] |  | svdh | B
Renvoie un en-tête d'entrée dans les en-têtes de sortie
RegisterHttpMethod méthode [méthode [...]] |  | s | C
Enregistrement de méthodes HTTP non standards
RemoteIPHeader en-tête |  | sv | B
Définit le champ d'en-tête qui contiendra les adresses IP du client
RemoteIPInternalProxy ip-mandataire|ip-mandataire/sous-réseau|nom-hôte ... |  | sv | B
Déclare les adresses IP intranet clients comme dignes de confiance pour présenter la valeur RemoteIPHeader
RemoteIPInternalProxyList nom-fichier |  | sv | B
Déclare les adresses IP intranet clients comme dignes de confiance pour présenter la valeur RemoteIPHeader
RemoteIPProxiesHeader Nom_en-tête |  | sv | B
Déclare le champ d'en-tête qui contiendra toutes les adresses IP intermédiaires
RemoteIPProxyProtocol On|Off |  | sv | B
Active ou désactive la gestion du protocole PROXY
RemoteIPProxyProtocolExceptions host|range [host|range] [host|range] |  | sv | B
Désactive la prise en compte de l'en-tête PROXY pour certains hôtes ou réseaux
RemoteIPTrustedProxy ip-mandataire|ip-mandataire/sous-réseau|nom-hôte ... |  | sv | B
Déclare les adresses IP clientes de l'intranet dignes de confiance pour présenter la valeur RemoteIPHeader
RemoteIPTrustedProxyList nom-fichier |  | sv | B
Déclare les adresses IP intranet clients comme dignes de confiance pour présenter la valeur RemoteIPHeader
RemoveCharset extension [extension] ... |  | vdh | B
Supprime toute association de jeu de caractères pour un ensemble d'extensions de noms de fichiers
RemoveEncoding extension [extension] ... |  | vdh | B
Supprime toute association de codage de contenu pour un ensemble d'extensions de noms de fichiers
RemoveHandler extension [extension] ... |  | vdh | B
Supprime toute association de gestionnaire à un ensemble d'extensions de noms de fichiers
RemoveInputFilter extension [extension] ... |  | vdh | B
Supprime toute association de filtre en entrée à un ensemble d'extensions de noms de fichiers
RemoveLanguage extension [extension] ... |  | vdh | B
Supprime toute association de langue à un ensemble d'extensions de noms de fichiers
RemoveOutputFilter extension [extension] ... |  | vdh | B
Supprime toute association de filtre en sortie à un ensemble d'extensions de noms de fichiers
RemoveType extension [extension] ... |  | vdh | B
Supprime toute association de type de contenu à un ensemble d'extensions de noms de fichiers
RequestHeader add|append|edit|edit*|merge|set|setifempty|unset en-tête [[expr=]valeur [remplacement] [early|env=[!]variable|expr=expression]] |  | svdh | E
Configure les en-têtes d'une requête HTTP
RequestReadTimeout [header=délai[-délai-maxi][,MinRate=taux-mini] [body=délai[-délai-maxi][,MinRate=taux-mini] |  | sv | E
Définit des délais maximums pour la réception des en-têtes et corps des requêtes en provenance du client.
Require [not] nom-entité [nom-entité] ... |  | dh | B
Vérifie si un utilisateur authentifié a une autorisation d'accès accordée par un fournisseur d'autorisation.
<RequireAll> ... </RequireAll> |  | dh | B
Regroupe plusieurs directives d'autorisation dont aucune ne doit échouer et dont au moins une doit retourner un résultat positif pour que la directive globale retourne elle-même un résultat positif.
<RequireAny> ... </RequireAny> |  | dh | B
Regroupe des directives d'autorisation dont au moins une doit retourner un résultat positif pour que la directive globale retourne elle-même un résultat positif.
<RequireNone> ... </RequireNone> |  | dh | B
Regroupe des directives d'autorisation dont aucune ne doit retourner un résultat positif pour que la directive globale n'échoue pas.
RewriteBase chemin_URL |  | dh | E
Définit l'URL de base pour les réécritures au niveau répertoire
RewriteCond chaîne_de_test expression_de_comparaison [drapeaux] |  | svdh | E
Définit une condition qui devra être satisfaite pour que la réécriture soit effectuée
RewriteEngine on|off | off | svdh | E
Active ou désactive l'exécution du moteur de réécriture
RewriteMap MapName MapType:MapSource |  | sv | E
Définit une fonction de mise en correspondance pour la recherche de mots-clés
RewriteOptions Options |  | svdh | E
Configure certaines options spéciales pour le moteur de réécriture
RewriteRule Modèle Substitution [drapeaux] |  | svdh | E
Définit les règles pour le moteur de réécriture
RLimitCPU secondes|max [secondes|max] |  | svdh | C
Limite le temps CPU alloué aux processus initiés par les processus enfants d'Apache httpd
RLimitMEM octets|max [octets|max] |  | svdh | C
Limite la mémoire allouée aux processus initiés par les processus enfants d'Apache httpd
RLimitNPROC nombre|max [nombre|max] |  | svdh | C
Limite le nombre de processus qui peuvent être initiés par les processus initiés par les processus enfants d'Apache httpd
Satisfy Any|All | All | dh | E
Interaction entre le contrôle d'accès en fonction de l'hôte et l'authentification utilisateur
ScoreBoardFile chemin fichier | logs/apache_runtime + | s | M
Chemin du fichier où sont stockées les données concernant la coordination des processus enfants
Script méthode script cgi |  | svd | B
Active un script CGI dans le cas d'une méthode de requête particulière.
ScriptAlias [chemin URL] chemin fichier|chemin répertoire |  | svd | B
Fait correspondre une URL à une zone du système de fichiers et désigne la cible comme script CGI
ScriptAliasMatch regex chemin fichier|chemin répertoire |  | sv | B
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
ScriptInterpreterSource Registry|Registry-Strict|Script | Script | svdh | C
Permet de localiser l'interpréteur des scripts CGI
ScriptLog chemin fichier |  | sv | B
Chemin du fichier journal des erreurs du script CGI
ScriptLogBuffer octets | 1024 | sv | B
Taille maximale des requêtes PUT ou POST qui seront enregistrées dans le journal du script
ScriptLogLength octets | 10385760 | sv | B
Taille maximale du fichier journal des scripts CGI
ScriptSock chemin fichier | cgisock | s | B
Le préfixe du nom de fichier du socket à utiliser pour communiquer avec le démon CGI
SecureListen [adresse-IP:]num-port nom-certificat [MUTUAL] |  | s | B
Active le chiffrement SSL pour le port spécifié
SeeRequestTail On|Off | Off | s | C
Détermine si mod_status affiche les 63 premiers caractères d'une requête ou les 63 derniers, en supposant que la requête elle-même possède plus de 63 caractères.
SendBufferSize octets | 0 | s | M
Taille du tampon TCP en sortie
ServerAdmin adresse électronique|URL |  | sv | C
L'adresse électronique que le serveur inclut dans les messages d'erreur envoyés au client
ServerAlias nom serveur [nom serveur] ... |  | v | C
Autres noms d'un serveur utilisables pour atteindre des serveurs virtuels à base de nom
ServerLimit nombre |  | s | M
Limite supérieure de la définition du nombre de processus
ServerName [protocole://]nom-de-domaine|adresse-ip[:port] |  | sv | C
Nom d'hôte et port que le serveur utilise pour s'authentifier lui-même
ServerPath chemin d'URL |  | v | C
Nom de chemin d'URL hérité pour un serveur virtuel à base de nom accédé par un navigateur incompatible
ServerRoot chemin de répertoire | /usr/local/apache | s | C
Racine du répertoire d'installation du serveur
ServerSignature On|Off|EMail | Off | svdh | C
Définit un pied de page pour les documents générés par le serveur
ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full | Full | s | C
Configure l'en-tête Server de la réponse HTTP
Session On|Off | Off | svdh | E
Ouvre une session pour le contexte courant
SessionCookieName nom attributs |  | svdh | E
Nom et attributs du cookie RFC2109 dans lequel la session est stockée
SessionCookieName2 nom attributs |  | svdh | E
Nom et attributs pour le cookie RFC2965 dans lequel est stockée la session
SessionCookieRemove On|Off | Off | svdh | E
Détermine si les cookies de session doivent être supprimés des en-têtes HTTP entrants
SessionCryptoCipher algorithme |  | svdh | X
L'algorithme à utiliser pour le chiffrement de la session
SessionCryptoDriver nom [param[=valeur]] |  | s | X
Le pilote de chiffrement à utiliser pour chiffrer les sessions
SessionCryptoPassphrase secret [ secret ... ] |  | svdh | X
La clé utilisée pour chiffrer la session
SessionCryptoPassphraseFile nom-fichier |  | svd | X
Le fichier contenant les clés utilisées pour chiffrer la session
SessionDBDCookieName nom attributs |  | svdh | E
Nom et attributs du cookie RFC2109 qui contient l'identifiant de session
SessionDBDCookieName2 nom attributs |  | svdh | E
Nom et attributs du cookie RFC2965 qui contient l'identifiant de session
SessionDBDCookieRemove On|Off | On | svdh | E
Détermine si les cookies de session doivent être supprimés des en-têtes HTTP entrants
SessionDBDDeleteLabel étiquette | deletesession | svdh | E
La requête SQL à utiliser pour supprimer des sessions de la base de données
SessionDBDInsertLabel étiquette | insertsession | svdh | E
La requête SQL à utiliser pour insérer des sessions dans la base de données
SessionDBDPerUser On|Off | Off | svdh | E
Active une session propre à un utilisateur
SessionDBDSelectLabel étiquette | selectsession | svdh | E
La requête SQL à utiliser pour sélectionner des sessions dans la base de données
SessionDBDUpdateLabel étiquette | updatesession | svdh | E
La requête SQL à utiliser pour mettre à jour des sessions préexistantes dans la base de données
SessionEnv On|Off | Off | svdh | E
Définit si le contenu de la session doit être enregistré dans la variable d'environnement HTTP_SESSION
SessionExclude chemin |  | svdh | E
Définit les préfixes d'URLs pour lesquels une session sera ignorée
SessionHeader en-tête |  | svdh | E
Importation des mises à jour de session depuis l'en-tête de réponse HTTP spécifié
SessionInclude chemin |  | svdh | E
Définit les préfixes d'URL pour lesquels une session est valide
SessionMaxAge durée de vie maximale | 0 | svdh | E
Définit une durée de vie maximale pour la session en secondes
SetEnv var-env [valeur] |  | svdh | B
Définit des variables d'environnement
SetEnvIf attribut regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ... |  | svdh | B
Définit des variables d'environnement en fonction des attributs de la requête
SetEnvIfExpr expr [!]env-variable[=valeur] [[!]env-variable[=valeur]] ... |  | svdh | B
Définit des variables d'environnement en fonction d'une expression ap_expr
SetEnvIfNoCase attribut regex [!]env-variable[=valeur] [[!]env-variable[=valeur]] ... |  | svdh | B
Définit des variables d'environnement en fonction des attributs de la requête sans tenir compte de la casse
SetHandler handler-name|none|expression |  | svdh | C
Force le traitement des fichiers spécifiés par un gestionnaire particulier
SetInputFilter filtre[;filtre...] |  | svdh | C
Définit les filtres par lesquels vont passer les requêtes client et les données POST
SetOutputFilter filtre[;filtre...] |  | svdh | C
Définit les filtres par lesquels vont passer les réponses du serveur
SSIEndTag tag | "-->" | sv | B
Chaîne qui termine l'élément include
SSIErrorMsg message | "[an error occurred + | svdh | B
Message d'erreur affiché lorsqu'une erreur SSI survient
SSIETag on|off | off | dh | B
Définit si des en-têtes ETags sont générés par le serveur.
SSILastModified on|off | off | dh | B
Définit si des en-têtes Last-Modified sont générés par le serveur.
SSILegacyExprParser on|off | off | dh | B
Active le mode de compatibilité pour les expressions conditionnelles.
SSIStartTag tag | "<!--#" | sv | B
Chaîne qui marque le début d'un élément include
SSITimeFormat chaîne de formatage | "%A, %d-%b-%Y %H:%M + | svdh | B
Configuration du format d'affichage des dates
SSIUndefinedEcho chaîne | "(none)" | svdh | B
Chaîne à afficher lorsqu'on tente d'extraire le contenu d'une variable non définie
SSLCACertificateFile chemin-fichier |  | sv | E
Fichier contenant une concaténation des certificats de CA codés en PEM pour l'authentification des clients
SSLCACertificatePath chemin-répertoire |  | sv | E
Répertoire des certificats de CA codés en PEM pour l'authentification des clients
SSLCADNRequestFile chemin-fichier |  | sv | E
Fichier contenant la concaténation des certificats de CA codés en PEM pour la définition de noms de CA acceptables
SSLCADNRequestPath chemin-répertoire |  | sv | E
Répertoire contenant des fichiers de certificats de CA codés en PEM pour la définition de noms de CA acceptables
SSLCARevocationCheck chain|leaf|none flags | none | sv | E
Active la vérification des révocations basée sur les CRL
SSLCARevocationFile chemin-fichier |  | sv | E
Fichier contenant la concaténation des CRLs des CA codés en PEM pour l'authentification des clients
SSLCARevocationPath chemin-répertoire |  | sv | E
Répertoire des CRLs de CA codés en PEM pour l'authentification des clients
SSLCertificateChainFile chemin-fichier |  | sv | E
Fichier contenant les certificats de CA du serveur codés en PEM
SSLCertificateFile chemin-fichier |  | sv | E
Fichier de données contenant le certificat X.509 du serveur codé en PEM
SSLCertificateKeyFile chemin-fichier |  | sv | E
Fichier contenant la clé privée du serveur codée en PEM
SSLCipherSuite algorithmes | DEFAULT (dépend de + | svdh | E
Algorithmes de chiffrement disponibles pour la négociation au cours de l'initialisation de la connexion SSL
SSLCompression on|off | off | sv | E
Permet d'activer la compression au niveau SSL
SSLCryptoDevice moteur | builtin | s | E
Active l'utilisation d'un accélérateur matériel de chiffrement
SSLEngine on|off|optional | off | sv | E
Interrupteur marche/arrêt du moteur SSL
SSLFIPS on|off | off | s | E
Coimmutateur du mode SSL FIPS
SSLHonorCipherOrder on|off | off | sv | E
Option permettant de classer les algorithmes de chiffrement du serveur par ordre de préférence
SSLInsecureRenegotiation on|off | off | sv | E
Option permettant d'activer le support de la renégociation non sécurisée
SSLOCSDefaultResponder uri |  | sv | E
Définit l'URI du répondeur par défaut pour la validation OCSP
SSLOCSPEnable on|off | off | sv | E
Active la validation OCSP de la chaîne de certificats du client
SSLOCSPNoverify On/Off | Off | sv | E
Evite la vérification des certificats des répondeurs OCSP
SSLOCSPOverrideResponder on|off | off | sv | E
Force l'utilisation de l'URI du répondeur par défaut pour la validation OCSP
SSLOCSPProxyURL url |  | sv | E
Adresse de mandataire à utiliser pour les requêtes OCSP
SSLOCSPResponderCertificateFile file |  | sv | E
Fournit un jeu de certificats de confiance du répondeur OCSP avec encodage PEM
SSLOCSPResponderTimeout secondes | 10 | sv | E
Délai d'attente pour les requêtes OCSP
SSLOCSPResponseMaxAge secondes | -1 | sv | E
Age maximum autorisé pour les réponses OCSP
SSLOCSPResponseTimeSkew secondes | 300 | sv | E
Dérive temporelle maximale autorisée pour la validation des réponses OCSP
SSLOCSPUseRequestNonce on|off | on | sv | E
Use a nonce within OCSP queries
SSLOpenSSLConfCmd commande valeur |  | sv | E
Configuration des paramètres d'OpenSSL via son API SSL_CONF
SSLOptions [+|-]option ... |  | svdh | E
Configure différentes options d'exécution du moteur SSL
SSLPassPhraseDialog type | builtin | s | E
Méthode utilisée pour entrer le mot de passe pour les clés privées chiffrées
SSLProtocol [+|-]protocole ... | all -SSLv3 (jusqu'à + | sv | E
Indique les versions du protocole SSL/TLS disponibles
SSLProxyCACertificateFile file-path |  | sv | E
Fichier contenant la concaténation des certificats de CA codés en PEM pour l'authentification des serveurs distants
SSLProxyCACertificatePath chemin-répertoire |  | sv | E
Répertoire des certificats de CA codés en PEM pour l'authentification des serveurs distants
SSLProxyCARevocationCheck chain|leaf|none | none | sv | E
Active la vérification des révocations basée sur les CRLs pour l'authentification du serveur distant
SSLProxyCARevocationFile chemin-fichier |  | sv | E
Fichier contenant la concaténation des CRLs de CA codés en PEM pour l'authentification des serveurs distants
SSLProxyCARevocationPath chemin-répertoire |  | sv | E
Répertoire des CRLs de CA codés en PEM pour l'authentification des serveurs distants
SSLProxyCheckPeerCN on|off | on | sv | E
Configuration de la vérification du champ CN du certificat du serveur distant
SSLProxyCheckPeerExpire on|off | on | sv | E
Configuration de la vérification de l'expiration du certificat du serveur distant
SSLProxyCheckPeerName on|off | on | sv | E
Configure la vérification du nom d'hôte dans les certificats serveur distants
SSLProxyCipherSuite algorithmes | ALL:!ADH:RC4+RSA:+H + | sv | E
Algorithmes de chiffrement disponibles pour la négociation lors de l'initialisation d'une connexion SSL de mandataire
SSLProxyEngine on|off | off | sv | E
Interrupteur marche/arrêt du moteur de mandataire SSL
SSLProxyMachineCertificateChainFile nom-fichier |  | sv | E
Fichier de certificats de CA encodés PEM concaténés permettant au mandataire de choisir un certificat
SSLProxyMachineCertificateFile chemin-fichier |  | sv | E
Fichier contenant la concaténation des clés et certificats clients codés en PEM que le mandataire doit utiliser
SSLProxyMachineCertificatePath chemin-répertoire |  | sv | E
Répertoire des clés et certificats clients codés en PEM que le mandataire doit utiliser
SSLProxyProtocol [+|-]protocole ... | all -SSLv3 (jusqu'à + | sv | E
Définit les protocoles SSL disponibles pour la fonction de mandataire
SSLProxyVerify niveau | none | sv | E
Niveau de vérification du certificat du serveur distant
SSLProxyVerifyDepth niveau | 1 | sv | E
Niveau de profondeur maximum dans les certificats de CA lors de la vérification du certificat du serveur distant
SSLRandomSeed contexte source [nombre] |  | s | E
Source de déclenchement du Générateur de Nombres Pseudo-Aléatoires (PRNG)
SSLRenegBufferSize taille | 131072 | dh | E
Définit la taille du tampon de renégociation SSL
SSLRequire expression |  | dh | E
N'autorise l'accès que lorsqu'une expression booléenne complexe et arbitraire est vraie
SSLRequireSSL |  | dh | E
Interdit l'accès lorsque la requête HTTP n'utilise pas SSL
SSLSessionCache type | none | s | E
Type du cache de session SSL global et inter-processus
SSLSessionCacheTimeout secondes | 300 | sv | E
Nombre de secondes avant l'expiration d'une session SSL dans le cache de sessions
SSLSessionTicketKeyFile chemin-fichier |  | sv | E
Clé de chiffrement/déchiffrement permanente pour les tickets de session TLS
SSLSessionTickets on|off | on | sv | E
Active ou désactive les tickets de session TLS
SSLSRPUnknownUserSeed secret-string |  | sv | E
Source d'aléa pour utilisateur SRP inconnu
SSLSRPVerifierFile file-path |  | sv | E
Chemin du fichier de vérification SRP
SSLStaplingCache type |  | s | E
Configuration du cache pour l'agrafage OCSP
SSLStaplingErrorCacheTimeout secondes | 600 | sv | E
Durée de vie des réponses invalides dans le cache pour agrafage OCSP
SSLStaplingFakeTryLater on|off | on | sv | E
Génère une réponse "tryLater" pour les requêtes OCSP échouées
SSLStaplingForceURL uri |  | sv | E
Remplace l'URI du serveur OCSP spécifié dans l'extension AIA du certificat
SSLStaplingResponderTimeout secondes | 10 | sv | E
Temps d'attente maximum pour les requêtes vers les serveurs OCSP
SSLStaplingResponseMaxAge secondes | -1 | sv | E
Age maximum autorisé des réponses OCSP incluses dans la négociation TLS
SSLStaplingResponseTimeSkew secondes | 300 | sv | E
Durée de vie maximale autorisée des réponses OCSP incluses dans la négociation TLS
SSLStaplingReturnResponderErrors on|off | on | sv | E
Transmet au client les erreurs survenues lors des requêtes OCSP
SSLStaplingStandardCacheTimeout secondes | 3600 | sv | E
Durée de vie des réponses OCSP dans le cache
SSLStrictSNIVHostCheck on|off | off | sv | E
Contrôle de l'accès des clients non-SNI à un serveur virtuel à base de nom.
SSLUserName nom-var |  | sdh | E
Nom de la variable servant à déterminer le nom de l'utilisateur
SSLUseStapling on|off | off | sv | E
Active l'ajout des réponses OCSP à la négociation TLS
SSLVerifyClient niveau | none | svdh | E
Niveau de vérification du certificat client
SSLVerifyDepth nombre | 1 | svdh | E
Profondeur maximale des certificats de CA pour la vérification des certificats clients
StartServers nombre |  | s | M
Nombre de processus enfants du serveur créés au démarrage
StartThreads nombre |  | s | M
Nombre de threads créés au démarrage
Substitute s/modèle/substitution/[infq] |  | dh | E
Modèle de substition dans le contenu de la réponse
SubstituteInheritBefore on|off | on | dh | E
Modifie l'ordre de fusion des modèles hérités
SubstituteMaxLineLength octets(b|B|k|K|m|M|g|G) | 1m | dh | E
Définit la longueur de ligne maximale
Suexec On|Off |  | s | B
Active ou désactive la fonctionnalité suEXEC
SuexecUserGroup Utilisateur Groupe |  | sv | E
L'utilisateur et le groupe sous lesquels les programmes CGI doivent s'exécuter
ThreadLimit nombre |  | s | M
Le nombre de threads maximum que l'on peut définir par processus enfant
ThreadsPerChild nombre |  | s | M
Nombre de threads créés par chaque processus enfant
ThreadStackSize taille |  | s | M
La taille en octets de la pile qu'utilisent les threads qui traitent les connexions clients
TimeOut secondes | 60 | sv | C
Temps pendant lequel le serveur va attendre certains évènements avant de considérer qu'une requête a échoué
TraceEnable [on|off|extended] | on | sv | C
Détermine le comportement des requêtes TRACE
TransferLog fichier|pipe |  | sv | B
Spécifie l'emplacement d'un fichier journal
TypesConfig chemin-fichier | conf/mime.types | s | B
Le chemin du fichier mime.types
UnDefine nom-variable |  | s | C
Invalide la définition d'une variable
UndefMacro nom |  | svd | B
Supprime une macro
UnsetEnv var-env [var-env] ... |  | svdh | B
Supprime des variables de l'environnement
Use nom [valeur1 ... valeurN] |  | svd | B
Utilisation d'une macro
UseCanonicalName On|Off|DNS | Off | svd | C
Définit la manière dont le serveur détermine son propre nom et son port
UseCanonicalPhysicalPort On|Off | Off | svd | C
Définit la manière dont le serveur détermine son propre port
User utilisateur unix | #-1 | s | B
L'utilisateur sous lequel le serveur va traiter les requêtes
UserDir nom-répertoire [nom-répertoire] ... |  | sv | B
Chemin des répertoires propres à un utilisateur
VHostCGIMode On|Off|Secure | On | v | X
Détermine si le serveur virtuel peut exécuter des sous-processus, et définit les privilèges disponibles pour ces dernier.
VHostPrivs [+-]?nom-privilège [[+-]?nom-privilège] ... |  | v | X
Assigne des privilèges au choix aux sous-processus créés par un serveur virtuel.
VHostGroup identifiant-groupe-unix |  | v | X
Définit l'identifiant du groupe sous lequel s'exécute un serveur virtuel.
VHostPrivs [+-]?nom-privilège [[+-]?nom-privilège] ... |  | v | X
Assigne des privilèges à un serveur virtuel.
VHostSecure On|Off | On | v | X
Détermine si le serveur s'exécute avec une sécurité avancée pour les serveurs virtuels.
VHostUser identifiant-utilisateur-unix |  | v | X
Définit l'identifiant utilisateur sous lequel s'exécute un serveur virtuel.
VirtualDocumentRoot répertoire-interpolé|none | none | sv | E
Permet une configuration dynamique de la racine des documents d'un serveur virtuel donné
VirtualDocumentRootIP répertoire-interpolé|none | none | sv | E
Configuration dynamique de la racine des documents pour un serveur virtuel donné
<VirtualHost adresse IP[:port] [adresse IP[:port]] ...> ... </VirtualHost> |  | s | C
Contient des directives qui ne s'appliquent qu'à un nom d'hôte spécifique ou à une adresse IP
VirtualScriptAlias répertoire-interpolé|none | none | sv | E
Configuration dynamique du répertoire des scripts CGI pour un serveur virtuel donné
VirtualScriptAliasIP répertoire-interpolé|none | none | sv | E
Configuration dynamique du répertoire des scripts CGI pour un serveur virtuel donné
WatchdogInterval number-of-seconds | 1 | s | B
Watchdog interval in seconds
XBitHack on|off|full | off | svdh | B
Interprète les directives SSI dans les fichiers dont le bit d'exécution est positionné
xml2EncAlias jeu-de-caractères alias [alias ...] |  | s | B
Définit des alias pour les valeurs d'encodage
xml2EncDefault nom |  | svdh | B
Définit un encodage par défaut à utiliser lorsqu'aucune information ne peut être automatiquement détectée
xml2StartParse élément [élément ...] |  | svdh | B
Indique à l'interpréteur à partir de quelle balise il doit commencer son traitement.


Override Class Index for .htaccess - Apache HTTP Server Version 2.4

Apache HTTP Server Version 2.4

Apache > HTTP Server > Documentation > Version 2.4

Override Class Index for .htaccess

This is an index of the directives that are allowed in .htaccess files for various AllowOverride settings, organized by class. Its intended purpose is to help server administrators verify the privileges they're granting to .htaccess users. For an overview of how .htaccess works, see the .htaccess tutorial.

To determine the set of directives that your server configuration allows .htaccess users to use:

  1. Start with the set of directives in the AllowOverrideList for the directory in question. (By default, this is set to None.)
  2. Find the AllowOverride setting for the directory in question. (By default, it is set to None.) There are two special cases:
    1. If your AllowOverride setting is All, add every directive listed on this page to the list.
    2. If your AllowOverride setting is None, you're done. Only the directives in the AllowOverrideList (if any) will be allowed.
  3. For each override class listed in AllowOverride, look up the corresponding set of directives below and add them to the list.
  4. Finally, add the set of directives that is always allowed in .htaccess (these are listed in the All section, below).

Several of the override classes are quite powerful and give .htaccess users a large amount of control over the server. For a stricter approach, set AllowOverride None and use AllowOverrideList to specify the exact list of directives that .htaccess users are allowed to use.

All

The following directives are allowed in any .htaccess file, as long as overrides are enabled in the server configuration.

<Else> | core
Contains directives that apply only if the condition of a previous <If> or <ElseIf> section is not satisfied by a request at runtime
<ElseIf> | core
Contains directives that apply only if a condition is satisfied by a request at runtime while the condition of a previous <If> or <ElseIf> section is not satisfied
<Files> | core
Contains directives that apply to matched filenames
<FilesMatch> | core
Contains directives that apply to regular-expression matched filenames
<If> | core
Contains directives that apply only if a condition is satisfied by a request at runtime
<IfDefine> | core
Encloses directives that will be processed only if a test is true at startup
<IfModule> | core
Encloses directives that are processed conditional on the presence or absence of a specific module
<IfVersion> | mod_version
contains version dependent configuration
LimitRequestBody | core
Restricts the total size of the HTTP request body sent from the client
LimitXMLRequestBody | core
Limits the size of an XML-based request body
LogIOTrackTTFB | mod_logio
Enable tracking of time to first byte (TTFB)
LuaCodeCache | mod_lua
Configure the compiled code cache.
LuaHookAccessChecker | mod_lua
Provide a hook for the access_checker phase of request processing
LuaHookAuthChecker | mod_lua
Provide a hook for the auth_checker phase of request processing
LuaHookCheckUserID | mod_lua
Provide a hook for the check_user_id phase of request processing
LuaHookFixups | mod_lua
Provide a hook for the fixups phase of a request processing
LuaHookInsertFilter | mod_lua
Provide a hook for the insert_filter phase of request processing
LuaHookLog | mod_lua
Provide a hook for the access log phase of a request processing
LuaHookMapToStorage | mod_lua
Provide a hook for the map_to_storage phase of request processing
LuaHookTranslateName | mod_lua
Provide a hook for the translate name phase of request processing
LuaHookTypeChecker | mod_lua
Provide a hook for the type_checker phase of request processing
LuaInherit | mod_lua
Controls how parent configuration sections are merged into children
LuaMapHandler | mod_lua
Map a path to a lua handler
LuaPackageCPath | mod_lua
Add a directory to lua's package.cpath
LuaPackagePath | mod_lua
Add a directory to lua's package.path
LuaQuickHandler | mod_lua
Provide a hook for the quick handler of request processing
LuaRoot | mod_lua
Specify the base path for resolving relative paths for mod_lua directives
LuaScope | mod_lua
One of once, request, conn, thread -- default is once
RLimitCPU | core
Limits the CPU consumption of processes launched by Apache httpd children
RLimitMEM | core
Limits the memory consumption of processes launched by Apache httpd children
RLimitNPROC | core
Limits the number of processes that can be launched by processes launched by Apache httpd children
ServerSignature | core
Configures the footer on server-generated documents
SSIErrorMsg | mod_include
Error message displayed when there is an SSI error
SSITimeFormat | mod_include
Configures the format in which date strings are displayed
SSIUndefinedEcho | mod_include
String displayed when an unset variable is echoed

AuthConfig

The following directives are allowed in .htaccess files when AllowOverride AuthConfig is in effect. They give .htaccess users control over the authentication and authorization methods that are applied to their directory subtrees, including several related utility directives for session handling and TLS settings.

Anonymous | mod_authn_anon
Specifies userIDs that are allowed access without password verification
Anonymous_LogEmail | mod_authn_anon
Sets whether the password entered will be logged in the error log
Anonymous_MustGiveEmail | mod_authn_anon
Specifies whether blank passwords are allowed
Anonymous_NoUserID | mod_authn_anon
Sets whether the userID field may be empty
Anonymous_VerifyEmail | mod_authn_anon
Sets whether to check the password field for a correctly formatted email address
AuthBasicAuthoritative | mod_auth_basic
Sets whether authorization and authentication are passed to lower level modules
AuthBasicFake | mod_auth_basic
Fake basic authentication using the given expressions for username and password
AuthBasicProvider | mod_auth_basic
Sets the authentication provider(s) for this location
AuthBasicUseDigestAlgorithm | mod_auth_basic
Check passwords against the authentication providers as if Digest Authentication was in force instead of Basic Authentication.
AuthDBMGroupFile | mod_authz_dbm
Sets the name of the database file containing the list of user groups for authorization
AuthDBMType | mod_authn_dbm
Sets the type of database file that is used to store passwords
AuthDBMUserFile | mod_authn_dbm
Sets the name of a database file containing the list of users and passwords for authentication
AuthDigestAlgorithm | mod_auth_digest
Selects the algorithm used to calculate the challenge and response hashes in digest authentication
AuthDigestDomain | mod_auth_digest
URIs that are in the same protection space for digest authentication
AuthDigestNonceLifetime | mod_auth_digest
How long the server nonce is valid
AuthDigestProvider | mod_auth_digest
Sets the authentication provider(s) for this location
AuthDigestQop | mod_auth_digest
Determines the quality-of-protection to use in digest authentication
AuthFormAuthoritative | mod_auth_form
Sets whether authorization and authentication are passed to lower level modules
AuthFormProvider | mod_auth_form
Sets the authentication provider(s) for this location
AuthGroupFile | mod_authz_groupfile
Sets the name of a text file containing the list of user groups for authorization
AuthLDAPAuthorizePrefix | mod_authnz_ldap
Specifies the prefix for environment variables set during authorization
AuthLDAPBindAuthoritative | mod_authnz_ldap
Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.
AuthLDAPBindDN | mod_authnz_ldap
Optional DN to use in binding to the LDAP server
AuthLDAPBindPassword | mod_authnz_ldap
Password used in conjunction with the bind DN
AuthLDAPCompareAsUser | mod_authnz_ldap
Use the authenticated user's credentials to perform authorization comparisons
AuthLDAPCompareDNOnServer | mod_authnz_ldap
Use the LDAP server to compare the DNs
AuthLDAPDereferenceAliases | mod_authnz_ldap
When will the module de-reference aliases
AuthLDAPGroupAttribute | mod_authnz_ldap
LDAP attributes used to identify the user members of groups.
AuthLDAPGroupAttributeIsDN | mod_authnz_ldap
Use the DN of the client username when checking for group membership
AuthLDAPInitialBindAsUser | mod_authnz_ldap
Determines if the server does the initial DN lookup using the basic authentication users' own username, instead of anonymously or with hard-coded credentials for the server
AuthLDAPInitialBindPattern | mod_authnz_ldap
Specifies the transformation of the basic authentication username to be used when binding to the LDAP server to perform a DN lookup
AuthLDAPMaxSubGroupDepth | mod_authnz_ldap
Specifies the maximum sub-group nesting depth that will be evaluated before the user search is discontinued.
AuthLDAPRemoteUserAttribute | mod_authnz_ldap
Use the value of the attribute returned during the user query to set the REMOTE_USER environment variable
AuthLDAPRemoteUserIsDN | mod_authnz_ldap
Use the DN of the client username to set the REMOTE_USER environment variable
AuthLDAPSearchAsUser | mod_authnz_ldap
Use the authenticated user's credentials to perform authorization searches
AuthLDAPSubGroupAttribute | mod_authnz_ldap
Specifies the attribute labels, one value per directive line, used to distinguish the members of the current group that are groups.
AuthLDAPSubGroupClass | mod_authnz_ldap
Specifies which LDAP objectClass values identify directory objects that are groups during sub-group processing.
AuthLDAPUrl | mod_authnz_ldap
URL specifying the LDAP search parameters
AuthMerging | mod_authz_core
Controls the manner in which each configuration section's authorization logic is combined with that of preceding configuration sections.
AuthName | mod_authn_core
Authorization realm for use in HTTP authentication
AuthnCacheProvideFor | mod_authn_socache
Specify which authn provider(s) to cache for
AuthnCacheTimeout | mod_authn_socache
Set a timeout for cache entries
AuthType | mod_authn_core
Type of user authentication
AuthUserFile | mod_authn_file
Sets the name of a text file containing the list of users and passwords for authentication
AuthzDBMType | mod_authz_dbm
Sets the type of database file that is used to store list of user groups
CGIPassAuth | core
Enables passing HTTP authorization headers to scripts as CGI variables
LDAPReferralHopLimit | mod_ldap
The maximum number of referral hops to chase before terminating an LDAP query.
LDAPReferrals | mod_ldap
Enable referral chasing during queries to the LDAP server.
<Limit> | core
Restrict enclosed access controls to only certain HTTP methods
<LimitExcept> | core
Restrict access controls to all HTTP methods except the named ones
Require | mod_authz_core
Tests whether an authenticated user is authorized by an authorization provider.
<RequireAll> | mod_authz_core
Enclose a group of authorization directives of which none must fail and at least one must succeed for the enclosing directive to succeed.
<RequireAny> | mod_authz_core
Enclose a group of authorization directives of which one must succeed for the enclosing directive to succeed.
<RequireNone> | mod_authz_core
Enclose a group of authorization directives of which none must succeed for the enclosing directive to not fail.
Satisfy | mod_access_compat
Interaction between host-level access control and user authentication
Session | mod_session
Enables a session for the current directory or location
SessionEnv | mod_session
Control whether the contents of the session are written to the HTTP_SESSION environment variable
SessionHeader | mod_session
Import session updates from a given HTTP response header
SessionInclude | mod_session
Define URL prefixes for which a session is valid
SessionMaxAge | mod_session
Define a maximum age in seconds for a session
SSLCipherSuite | mod_ssl
Cipher Suite available for negotiation in SSL handshake
SSLRenegBufferSize | mod_ssl
Set the size for the SSL renegotiation buffer
SSLRequire | mod_ssl
Allow access only when an arbitrarily complex boolean expression is true
SSLRequireSSL | mod_ssl
Deny access when SSL is not used for the HTTP request
SSLUserName | mod_ssl
Variable name to determine user name
SSLVerifyClient | mod_ssl
Type of Client Certificate verification
SSLVerifyDepth | mod_ssl
Maximum depth of CA Certificates in Client Certificate verification

FileInfo

The following directives are allowed in .htaccess files when AllowOverride FileInfo is in effect. They give .htaccess users a wide range of control over the responses and metadata given by the server.

AcceptPathInfo | core
Resources accept trailing pathname information
Action | mod_actions
Activates a CGI script for a particular handler or content-type
AddCharset | mod_mime
Maps the given filename extensions to the specified content charset
AddDefaultCharset | core
Default charset parameter to be added when a response content-type is text/plain or text/html
AddEncoding | mod_mime
Maps the given filename extensions to the specified encoding type
AddHandler | mod_mime
Maps the filename extensions to the specified handler
AddInputFilter | mod_mime
Maps filename extensions to the filters that will process client requests
AddLanguage | mod_mime
Maps the given filename extension to the specified content language
AddOutputFilter | mod_mime
Maps filename extensions to the filters that will process responses from the server
AddOutputFilterByType | mod_filter
assigns an output filter to a particular media-type
AddType | mod_mime
Maps the given filename extensions onto the specified content type
BrowserMatch | mod_setenvif
Sets environment variables conditional on HTTP User-Agent
BrowserMatchNoCase | mod_setenvif
Sets environment variables conditional on User-Agent without respect to case
CGIMapExtension | core
Technique for locating the interpreter for CGI scripts
CGIVar | core
Controls how some CGI variables are set
CharsetDefault | mod_charset_lite
Charset to translate into
CharsetOptions | mod_charset_lite
Configures charset translation behavior
CharsetSourceEnc | mod_charset_lite
Source charset of files
CookieDomain | mod_usertrack
The domain to which the tracking cookie applies
CookieExpires | mod_usertrack
Expiry time for the tracking cookie
CookieName | mod_usertrack
Name of the tracking cookie
CookieStyle | mod_usertrack
Format of the cookie header field
CookieTracking | mod_usertrack
Enables tracking cookie
DefaultLanguage | mod_mime
Defines a default language-tag to be sent in the Content-Language header field for all resources in the current context that have not been assigned a language-tag by some other means.
DefaultType | core
This directive has no effect other than to emit warnings if the value is not none. In prior versions, DefaultType would specify a default media type to assign to response content for which no other media type configuration could be found.
EnableMMAP | core
Use memory-mapping to read files during delivery
EnableSendfile | core
Use the kernel sendfile support to deliver files to the client
ErrorDocument | core
What the server will return to the client in case of an error
FileETag | core
File attributes used to create the ETag HTTP response header for static files
ForceLanguagePriority | mod_negotiation
Action to take if a single acceptable document is not found
ForceType | core
Forces all matching files to be served with the specified media type in the HTTP Content-Type header field
Header | mod_headers
Configure HTTP response headers
ISAPIAppendLogToErrors | mod_isapi
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the error log
ISAPIAppendLogToQuery | mod_isapi
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field
ISAPIFakeAsync | mod_isapi
Fake asynchronous support for ISAPI callbacks
ISAPILogNotSupported | mod_isapi
Log unsupported feature requests from ISAPI extensions
ISAPIReadAheadBuffer | mod_isapi
Size of the Read Ahead Buffer sent to ISAPI extensions
LanguagePriority | mod_negotiation
The precedence of language variants for cases where the client does not express a preference
MultiviewsMatch | mod_mime
The types of files that will be included when searching for a matching file with MultiViews
PassEnv | mod_env
Passes environment variables from the shell
QualifyRedirectURL | core
Controls whether the REDIRECT_URL environment variable is fully qualified
Redirect | mod_alias
Sends an external redirect asking the client to fetch a different URL
RedirectMatch | mod_alias
Sends an external redirect based on a regular expression match of the current URL
RedirectPermanent | mod_alias
Sends an external permanent redirect asking the client to fetch a different URL
RedirectTemp | mod_alias
Sends an external temporary redirect asking the client to fetch a different URL
RemoveCharset | mod_mime
Removes any character set associations for a set of file extensions
RemoveEncoding | mod_mime
Removes any content encoding associations for a set of file extensions
RemoveHandler | mod_mime
Removes any handler associations for a set of file extensions
RemoveInputFilter | mod_mime
Removes any input filter associations for a set of file extensions
RemoveLanguage | mod_mime
Removes any language associations for a set of file extensions
RemoveOutputFilter | mod_mime
Removes any output filter associations for a set of file extensions
RemoveType | mod_mime
Removes any content type associations for a set of file extensions
RequestHeader | mod_headers
Configure HTTP request headers
RewriteBase | mod_rewrite
Sets the base URL for per-directory rewrites
RewriteCond | mod_rewrite
Defines a condition under which rewriting will take place
RewriteEngine | mod_rewrite
Enables or disables runtime rewriting engine
RewriteOptions | mod_rewrite
Sets some special options for the rewrite engine
RewriteRule | mod_rewrite
Defines rules for the rewriting engine
ScriptInterpreterSource | core
Technique for locating the interpreter for CGI scripts
SetEnv | mod_env
Sets environment variables
SetEnvIf | mod_setenvif
Sets environment variables based on attributes of the request
SetEnvIfExpr | mod_setenvif
Sets environment variables based on an ap_expr expression
SetEnvIfNoCase | mod_setenvif
Sets environment variables based on attributes of the request without respect to case
SetHandler | core
Forces all matching files to be processed by a handler
SetInputFilter | core
Sets the filters that will process client requests and POST input
SetOutputFilter | core
Sets the filters that will process responses from the server
Substitute | mod_substitute
Pattern to filter the response content
SubstituteInheritBefore | mod_substitute
Change the merge order of inherited patterns
SubstituteMaxLineLength | mod_substitute
Set the maximum line size
UnsetEnv | mod_env
Removes variables from the environment

Indexes

The following directives are allowed in .htaccess files when AllowOverride Indexes is in effect. They allow .htaccess users to control aspects of the directory index pages provided by the server, including autoindex generation.

AddAlt | mod_autoindex
Alternate text to display for a file, instead of an icon selected by filename
AddAltByEncoding | mod_autoindex
Alternate text to display for a file instead of an icon selected by MIME-encoding
AddAltByType | mod_autoindex
Alternate text to display for a file, instead of an icon selected by MIME content-type
AddDescription | mod_autoindex
Description to display for a file
AddIcon | mod_autoindex
Icon to display for a file selected by name
AddIconByEncoding | mod_autoindex
Icon to display next to files selected by MIME content-encoding
AddIconByType | mod_autoindex
Icon to display next to files selected by MIME content-type
DefaultIcon | mod_autoindex
Icon to display for files when no specific icon is configured
DirectoryCheckHandler | mod_dir
Toggle how this module responds when another handler is configured
DirectoryIndex | mod_dir
List of resources to look for when the client requests a directory
DirectoryIndexRedirect | mod_dir
Configures an external redirect for directory indexes.
DirectorySlash | mod_dir
Toggle trailing slash redirects on or off
ExpiresActive | mod_expires
Enables generation of Expires headers
ExpiresByType | mod_expires
Value of the Expires header configured by MIME type
ExpiresDefault | mod_expires
Default algorithm for calculating expiration time
FallbackResource | mod_dir
Define a default URL for requests that don't map to a file
HeaderName | mod_autoindex
Name of the file that will be inserted at the top of the index listing
ImapBase | mod_imagemap
Default base for imagemap files
ImapDefault | mod_imagemap
Default action when an imagemap is called with coordinates that are not explicitly mapped
ImapMenu | mod_imagemap
Action if no coordinates are given when calling an imagemap
IndexHeadInsert | mod_autoindex
Inserts text in the HEAD section of an index page.
IndexIgnore | mod_autoindex
Adds to the list of files to hide when listing a directory
IndexIgnoreReset | mod_autoindex
Empties the list of files to hide when listing a directory
IndexOptions | mod_autoindex
Various configuration settings for directory indexing
IndexOrderDefault | mod_autoindex
Sets the default ordering of the directory index
IndexStyleSheet | mod_autoindex
Adds a CSS stylesheet to the directory index
MetaDir | mod_cern_meta
Name of the directory to find CERN-style meta information files
MetaFiles | mod_cern_meta
Activates CERN meta-file processing
MetaSuffix | mod_cern_meta
File name suffix for the file containing CERN-style meta information
ReadmeName | mod_autoindex
Name of the file that will be inserted at the end of the index listing

Limit

The following directives are allowed in .htaccess files when AllowOverride Limit is in effect. This extremely narrow override type mostly allows the use of the legacy authorization directives provided by mod_access_compat.

Allow | mod_access_compat
Controls which hosts can access an area of the server
Deny | mod_access_compat
Controls which hosts are denied access to the server
<Limit> | core
Restrict enclosed access controls to only certain HTTP methods
<LimitExcept> | core
Restrict access controls to all HTTP methods except the named ones
Order | mod_access_compat
Controls the default access state and the order in which Allow and Deny are evaluated.

Options

The following directives are allowed in .htaccess files when AllowOverride Options is in effect. They give .htaccess users access to Options and similar directives, as well as directives that control the filter chain.

CheckCaseOnly | mod_speling
Limits the action of the speling module to case corrections
CheckSpelling | mod_speling
Enables the spelling module
ContentDigest | core
Enables the generation of Content-MD5 HTTP Response headers
FilterChain | mod_filter
Configure the filter chain
FilterDeclare | mod_filter
Declare a smart filter
FilterProtocol | mod_filter
Deal with correct HTTP protocol handling
FilterProvider | mod_filter
Register a content filter
Options | core
Configures what features are available in a particular directory
ReflectorHeader | mod_reflector
Reflect an input header to the output headers
SSLOptions | mod_ssl
Configure various SSL engine run-time options
XBitHack | mod_include
Parse SSI directives in files with the execute bit set

Copyright 2018 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Pour démarrer - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Pour démarrer

Si vous ne connaissez rien au serveur HTTP Apache, ou même au fonctionnement d'un site web, vous vous demandez probablement par où commencer et quelles questions poser. Ce document vous permettra de parcourir les bases du sujet.

Clients, serveurs et URLs

Les adresses des pages web sur la Toile se présentent sous forme d'URLs - Uniform Resource Locators - qui comportent un protocole (par exemple http), un nom de serveur (par exemple www.apache.org), un chemin (par exemple /docs/current/getting-started.html), et le cas échéant une chaîne de requête (query string) (par exemple ?arg=value) permettant de transmettre des informations supplémentaires au serveur.

Un client (par exemple un navigateur web) se connecte à un serveur (par exemple votre serveur HTTP Apache) avec un protocole spécifique, et effectue une requête pour une ressource en spécifiant son chemin.

Un chemin peut représenter plusieurs types de ressources sur le serveur. Ce peut être un fichier (comme getting-started.html), un gestionnaire (comme server-status), ou toute sorte de programme (comme index.php). Nous décrirons tout ceci plus en détails ci-dessous dans la section Contenu d'un site web.

Le serveur envoie alors une réponse comportant un code d'état, et éventuellement un corps de réponse. Le code d'état indique si la requête a été traitée avec succès, ou dans la négative quel type d'erreur a été rencontré. Le client est alors sensé savoir quoi faire de la réponse. Vous pouvez vous familiariser avec les différents codes d'état en consultant le Wiki du serveur HTTP Apache.

Les détails de la transaction, ainsi que les erreurs rencontrées, sont enregistrés dans des fichiers journaux. Tout ceci est décrit en détails ci-dessous dans la section Débogage et fichiers journaux.

Noms d'hôte et DNS

Pour se connecter à un serveur, le client doit tout d'abord résoudre le nom du serveur en adresse IP, cette dernière permettant de localiser le serveur sur Internet. Ainsi, pour que votre serveur web soit accessible, son nom doit être enregistré dans le DNS.

Si vous ne savez pas comment effectuer cet enregistrement, vous devrez contacter votre administrateur réseau ou votre fournisseur d'accès à Internet afin qu'il effectue cette opération pour vous.

Plusieurs noms d'hôte peuvent pointer vers la même adresse IP, et plusieurs adresses IP peuvent être attachées au même serveur physique. Vous pouvez ainsi héberger plusieurs serveurs web sur le même serveur physique grâce au mécanisme des serveurs virtuels.

Pour tester un serveur non encore accessible sur Internet, vous pouvez renseigner son nom d'hôte dans votre fichier hosts afin d'effectuer une résolution de nom locale. Par exemple, pour tester le serveur web www.example.com depuis le serveur physique qui l'héberge, vous pouvez ajouter la ligne suivante au fichier hosts de ce dernier :

127.0.0.1 www.example.com

En général, le fichier hosts se trouve dans le répertoire /etc sur les systèmes de style Unix, ou C:\Windows\system32\drivers\etc sous Windows.

Vous trouverez plus de détails à propos du fichier hosts à Wikipedia.org/wiki/Hosts_(file), et à propos du DNS à Wikipedia.org/wiki/Domain_Name_System.

Fichiers de configuration et directives

La configuration du serveur HTTP Apache s'effectue via de simples fichiers textes. Ces fichiers peuvent se trouver dans de nombreux endroits différents en fonction du mode d'installation du serveur. Vous trouverez les positions courantes de ces fichiers dans le wiki httpd. Si vous installez httpd depuis le code source, le répertoire par défaut des fichiers de configuration est /usr/local/apache2/conf. Le nom du fichier de configuration par défaut est en général httpd.conf, mais peut aussi varier en fonction des distributions tierces du serveur.

L'ensemble de la configuration est en général divisé en plusieurs fichiers afin d'en faciliter la gestion. Ces fichiers sont inclus dans le fichier de configuration principal via la directive Include. Les noms ou positions de ces fichiers ne sont pas figés et peuvent varier considérablement d'une distribution à l'autre. N'hésitez pas à les arranger et subdiviser selon vos goûts et besoins, quitte à en modifier l'organisation par défaut.

La configuration du serveur s'effectue via des directives de configuration que l'on insère dans les fichiers de configuration. Une directive se compose d'un mot-clé suivi d'un ou plusieurs arguments qui définissent sa valeur.

La réponse à la question "Où dois-je placer cette directive ?" dépend en général du niveau auquel cette directive doit être prise en compte. S'il s'agit du niveau global, elle doit être placée dans le fichier de configuration principal, et en dehors de toute section <Directory>, <Location>, <VirtualHost>, ou de toute autre section. Si par exemple elle ne doit s'appliquer qu'à un répertoire particulier, elle doit être placée dans la section <Directory> qui fait référence à ce répertoire. Voir la documentation sur les Sections de configuration pour plus de détails.

En complément des fichiers de configuration principaux, certaines directives peuvent être insérées dans des fichiers .htaccess que l'on place directement dans le répertoire concerné. Les fichiers .htaccess sont essentiellement destinés aux personnes qui n'ont pas accès aux fichiers de configuration du serveur. Vous trouverez plus de détails à propos des fichiers .htaccess dans ce .htaccesshowto.

Contenu du site web

Si le contenu du site web peut se présenter sous de nombreuses formes, il peut en général être scindé en deux formes principales : les contenus statiques et les contenus dynamiques.

Les contenus statiques sont par exemple les fichiers HTML, les images, les fichiers CSS et tout autre fichier résidant dans le système de fichiers. La directive DocumentRoot permet de définir la position dans l'arborescence du site où vous devez placer ces fichiers. Cette directive peut être définie au niveau global, ou au niveau de chaque serveur virtuel. Vous pouvez consulter vos fichiers de configuration pour vérifier la manière dont cette directive est définie pour votre serveur.

En général, et si aucun nom de fichier n'est spécifié dans la requête, c'est une page de nom index.html qui sera renvoyée. Par exemple, si la directive DocumentRoot est définie à /var/www/html, et si une requête est effectuée pour l'adresse http://www.example.com/work/, c'est le fichier /var/www/html/work/index.html qui sera envoyé au client par le serveur.

Un contenu dynamique est un contenu qui est généré au moment du traitement de la requête, et qui peut différer d'une requête à l'autre. Ces contenus dynamiques peuvent être générés de nombreuses manières par l'intermédiaire de gestionnaires de contenu ou "handlers". Il est aussi possible de créer des programmes CGI pour générer le contenu de votre site.

Enfin, on peut utiliser des modules tiers comme mod_php pour écrire du code permettant d'effectuer de nombreuses choses. De nombreuses applications tierces écrites à partir de divers langages ou outils sont disponibles en téléchargement et peuvent être installées sur votre serveur HTTP Apache. Le support de ces applications dépasse le sujet de ce document, et nous vous invitons à consulter le site de leur éditeur pour accéder à leur documentation.

Fichiers journaux et résolution des problèmes

En tant qu'administrateur d'un serveur HTTP Apache, vos sources d'informations principales sont les fichiers journaux, et en particulier le journal des erreurs. Toute tentative de résolution d'un problème sans consulter le journal des erreurs revient à conduire les yeux fermés.

La position dans le système de fichiers du journal des erreurs est spécifiée par la directive ErrorLog qui peut être définie au niveau global, ou au niveau de chaque serveur virtuel. Chaque entrée du journal des erreurs vous informe sur la nature des problèmes et le moment de leur survenue. En outre, elle vous indique souvent comment résoudre le problème. Chaque message d'erreur contient un code d'erreur que vous pouvez utiliser pour effectuer une recherche en ligne afin d'obtenir une description plus détaillée de la manière de résoudre le problème. Vous pouvez aussi configurer votre journal des erreurs de manière à ce qu'il enregistre un identifiant d'erreur que vous pourrez ensuite utiliser pour effectuer une corrélation avec le journal des accès afin de déterminer quelle requête est à l'origine de l'erreur.

Vous trouverez plus de détails à ce sujet dans la Documentation sur la journalisation.

Et maintenant, quelle est la suite des opérations ?

La question des prérequis étant réglée, il est temps de passer aux choses sérieuses.

Ce document ne couvre que les notions de base. Nous espérons qu'il vous permettra de mettre le pied à l'étrier, mais il y a encore de nombreuses choses que vous devez savoir.

  • Téléchargement
  • Installation
  • Configuration
  • Démarrage du serveur
  • Foire aux questions


Plan du site - Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4

Plan du site

Cette page contient la liste des éléments actuellement disponibles de la Documentation du serveur HTTP Apache Version 2.4.

Notes de version

  • Mise à jour vers 2.4 depuis 2.2
  • Nouvelles fonctionnalités d'Apache 2.3/2.4
  • Nouvelles fonctionnalités d'Apache 2.1/2.2
  • Nouvelles fonctionnalités d'Apache 2.0
  • License Apache

Utilisation du serveur HTTP Apache

  • Compilation et installation
  • Démarrage
  • Arrêt ou redémarrage
  • Fichiers de configuration
  • Comment fonctionnent les sections Directory, Location et Files
  • Mise en cache du contenu
  • Configuration niveau serveur
  • Fichiers de traces
  • Mise en correspondance des URLs avec le système de fichiers
  • Objets Dynamiques Partagés (DSO)
  • Négociation sur le contenu
  • Messages d'erreur personnalisés
  • Définition des adresses et ports qu'utilise Apache
  • Modules multi-processus (MPMs)
  • Les variables d'environnement d'Apache
  • L'interprétation des expressions dans Apache
  • Utilisation des gestionnaires d'Apache
  • Filtres
  • Support du cache des objets partagés
  • Support de suEXEC
  • Considérations à propos de DNS et Apache
  • Foire aux Questions

Documentation des serveurs virtuels Apache

  • Aperçu
  • Serveurs virtuels basés sur le nom
  • Support des serveurs virtuels basés sur l'adresse IP
  • Configuration dynamique de l'hébergement virtuel de masse
  • Exemples de serveurs virtuels
  • Discussion approfondie à propos de la sélection d'un serveur virtuel
  • Limitations inhérentes aux descripteurs de fichiers

Guide de réécriture d'URLs

  • Survol
  • Documentation de référence de mod_rewrite
  • Introduction à l'utilisation des expressions rationnelles avec mod_rewrite
  • Utilisation de mod_rewrite pour les redirections et la traduction des URLs
  • Utilisation de mod_rewrite pour le contrôle d'accès
  • Les serveurs virtuels dynamique avec mod_rewrite
  • Le mandat dynamique avec mod_rewrite
  • Utilisation d'une table de réécriture
  • Techniques avancées
  • Quand ne pas utiliser mod_rewrite
  • Drapeaux de réécriture
  • Détails techniques

Chiffrement SSL/TLS avec Apache

  • Aperçu
  • Chiffrement SSL/TLS : Introduction
  • Chiffrement SSL/TLS : Compatibilité
  • Chiffrement SSL/TLS : Recettes
  • Chiffrement SSL/TLS : FAQ

Guides, Tutoriels, and Recettes

  • Aperçu
  • Authentification et autorisation
  • Contrôle d'accès
  • Contenu dynamique avec CGI
  • Introduction aux Inclusions côté serveur (Server Side Includes - SSI)
  • Fichiers .htaccess
  • Répertoires web des utilisateurs
  • Guide de configuration des mandataires inverses
  • Guide HTTP/2

Notes spécifiques à certains systèmes

  • Aperçu
  • Utiliser Apache avec Microsoft Windows
  • Compiler Apache pour Microsoft Windows
  • Utilisation d'Apache avec les systèmes à base de paquets RPM
  • Utiliser Apache avec Novell NetWare
  • Mise en oeuvre d'un serveur web hautes performances sous HPUX
  • Le portage d'Apache sous EBCDIC

Le serveur HTTP Apache et ses programmes associés

  • Aperçu
  • Page de manuel : httpd
  • Page de manuel : ab
  • Page de manuel : apachectl
  • Page de manuel : apxs
  • Page de manuel : configure
  • Page de manuel : dbmmanage
  • Page de manuel : fcgistarter
  • Page de manuel : htcacheclean
  • Page de manuel : htdbm
  • Page de manuel : htdigest
  • Page de manuel : htpasswd
  • Page de manuel : httxt2dbm
  • Page de manuel : logresolve
  • Page de manuel : log_server_status
  • Page de manuel : rotatelogs
  • Page de manuel : split-logfile
  • Page de manuel : suexec
  • Autres programmes

Documentations diverses sur Apache

  • Aperçu
  • Considérations à propos des performances - Configuration fine d'Apache
  • Conseils en matière de sécurité
  • Standards concernés
  • Formats de chiffrement des mots de passe

Modules Apache

  • Définitions des termes utilisés pour décrire les modules Apache
  • Définitions des termes utilisés pour décrire les directives Apache
  • Fonctionalités de Base Apache
  • Apache MPM : Directives Communes
  • Apache MPM event
  • Apache MPM netware
  • Apache MPM os2
  • Apache MPM prefork
  • Apache MPM winnt
  • Apache MPM worker
  • Module Apache mod_access_compat
  • Module Apache mod_actions
  • Module Apache mod_alias
  • Module Apache mod_allowmethods
  • Module Apache mod_asis
  • Module Apache mod_auth_basic
  • Module Apache mod_auth_digest
  • Module Apache mod_auth_form
  • Module Apache mod_authn_anon
  • Module Apache mod_authn_core
  • Module Apache mod_authn_dbd
  • Module Apache mod_authn_dbm
  • Module Apache mod_authn_file
  • Module Apache mod_authn_socache
  • Module Apache mod_authnz_fcgi
  • Module Apache mod_authnz_ldap
  • Module Apache mod_authz_core
  • Module Apache mod_authz_dbd
  • Module Apache mod_authz_dbm
  • Module Apache mod_authz_groupfile
  • Module Apache mod_authz_host
  • Module Apache mod_authz_owner
  • Module Apache mod_authz_user
  • Module Apache mod_autoindex
  • Module Apache mod_brotli
  • Module Apache mod_buffer
  • Module Apache mod_cache
  • Module Apache mod_cache_disk
  • Module Apache mod_cache_socache
  • Module Apache mod_cern_meta
  • Module Apache mod_cgi
  • Module Apache mod_cgid
  • Module Apache mod_charset_lite
  • Module Apache mod_data
  • Module Apache mod_dav
  • Module Apache mod_dav_fs
  • Module Apache mod_dav_lock
  • Module Apache mod_dbd
  • Module Apache mod_deflate
  • Module Apache mod_dialup
  • Module Apache mod_dir
  • Module Apache mod_dumpio
  • Module Apache mod_echo
  • Module Apache mod_env
  • Module Apache mod_example_hooks
  • Module Apache mod_expires
  • Module Apache mod_ext_filter
  • Module Apache mod_file_cache
  • Module Apache mod_filter
  • Module Apache mod_headers
  • Module Apache mod_heartbeat
  • Module Apache mod_heartmonitor
  • Module Apache mod_http2
  • Module Apache mod_ident
  • Module Apache mod_imagemap
  • Module Apache mod_include
  • Module Apache mod_info
  • Module Apache mod_isapi
  • Module Apache mod_lbmethod_bybusyness
  • Module Apache mod_lbmethod_byrequests
  • Module Apache mod_lbmethod_bytraffic
  • Module Apache mod_lbmethod_heartbeat
  • Module Apache mod_ldap
  • Module Apache mod_log_config
  • Module Apache mod_log_debug
  • Module Apache mod_log_forensic
  • Module Apache mod_logio
  • Module Apache mod_lua
  • Module Apache mod_macro
  • Module Apache mod_md
  • Module Apache mod_mime
  • Module Apache mod_mime_magic
  • Module Apache mod_negotiation
  • Module Apache mod_nw_ssl
  • Module Apache mod_privileges
  • Module Apache mod_proxy
  • Module Apache mod_proxy_ajp
  • Module Apache mod_proxy_balancer
  • Module Apache mod_proxy_connect
  • Module Apache mod_proxy_express
  • Module Apache mod_proxy_fcgi
  • Module Apache mod_proxy_fdpass
  • Module Apache mod_proxy_ftp
  • Module Apache mod_proxy_hcheck
  • Module Apache mod_proxy_html
  • Module Apache mod_proxy_http
  • Module Apache mod_proxy_http2
  • Module Apache mod_proxy_scgi
  • Module Apache mod_proxy_uwsgi
  • Module Apache mod_proxy_wstunnel
  • Module Apache mod_ratelimit
  • Module Apache mod_reflector
  • Module Apache mod_remoteip
  • Module Apache mod_reqtimeout
  • Module Apache mod_request
  • Module Apache mod_rewrite
  • Module Apache mod_sed
  • Module Apache mod_session
  • Module Apache mod_session_cookie
  • Module Apache mod_session_crypto
  • Module Apache mod_session_dbd
  • Module Apache mod_setenvif
  • Module Apache mod_slotmem_plain
  • Module Apache mod_slotmem_shm
  • Module Apache mod_so
  • Module Apache mod_socache_dbm
  • Module Apache mod_socache_dc
  • Module Apache mod_socache_memcache
  • Module Apache mod_socache_shmcb
  • Module Apache mod_speling
  • Module Apache mod_ssl
  • Module Apache mod_status
  • Module Apache mod_substitute
  • Module Apache mod_suexec
  • Module Apache mod_unique_id
  • Module Apache mod_unixd
  • Module Apache mod_userdir
  • Module Apache mod_usertrack
  • Module Apache mod_version
  • Module Apache mod_vhost_alias
  • Module Apache mod_watchdog
  • Module Apache mod_xml2enc

Documentation du développeur

  • Aperçu
  • Notes sur l'API Apache
  • Mises à jour de l'API dans Apache HTTPD 2.4
  • Développement de modules pour Apache HTTPD 2.4
  • Documentation d'Apache HTTPD
  • Fonctions d'accroche (Hook Functions) d'Apache 2.x
  • Convertir un module depuis la version 1.3 vers la version 2.x
  • Traitement des requêtes avec la version 2.x
  • Fonctionnement des filtres dans la version 2.x
  • Guide des filtres en sortie dans la version 2.x
  • Sécurité des threads dans la version 2.x

Glossaire et Index

  • Glossaire
  • Index des modules
  • Index des directives
  • Référence rapide des directives
  • Index des directives disponibles dans les fichiers .htaccess