Serveur Apache HTTP Version 2.0
Serveur Apache HTTP Version 2.0
Configuration des adresses et ports sur lesquels Apache coute.
Informations gnrales Prcisions au sujet d'IPv6 Faire fonctionner tout ceci avec les Serveurs Virtuels
| Modules Apparents | Directives Apparentes |
|---|---|
Au moment de son dmarrage, Apache se lie un port et une adresse sur la machine et se met en attente de requtes entrantes. Par dfaut, toutes les adresses de la machine se retrouvent l'coute. Dans tous les cas, Apache accepte d'couter sur un ou plusieurs ports spcifiques, ou sur une seule ou plusieurs adresses, ou encore une combinaison des deux. Il est frquent d'utiliser ces possibilits avec les fonctionnalits de Serveurs Virtuels, qui permettent de faire rpondre Apache de manire diffrente en fonction de l'adresse IP, du nom ou du port.
Le serveur utilise la directive
Listen
pour n'accepter que des requtes provenant de ports spcifiques ou
d'une combinaison adresse IP + port passs en argument.
Dans le cas o seul un port est spcifi avec la directive
Listen,
le serveur se met l'coute sur le port spcifi, sur toutes
les interfaces et adresses de la machine. Si une adresse IP est
prcise en plus du port, le serveur n'coute que sur l'adresse
et le port spcifis. Il est possible de configurer plusieurs
directives Listen,
afin qu'Apache coute sur plusieurs adresses
et ports. Dans ce cas, le serveur rpondra aux requtes faites
sur tous les adresses et ports numrs.
Par exemple, pour que le serveur accepte les connexions la fois sur les ports 80 et 8000, spcifiez :
Listen 80
Listen 8000
Pour qu'Apache accepte les connexions sur deux combinaisons adresses + ports, spcifiez :
Listen 192.170.2.1:80
Listen 192.170.2.5:8000
Les adresses IPv6 sont acceptes, pourvu qu'elles soient entoures entre crochets de la faon suivante :
Listen [2001:db8::a00:20ff:fea7:ccea]:80
De plus en plus de plates-formes implmentent IPv6, et APR supporte IPv6 sur la plupart d'entre elles, si bien qu'Apache peut utiliser des sockets IPv6 et rpondre aux requtes envoyes en IPv6.
Une complication possible pour les administrateurs Apache est de
savoir si un socket IPv6 est capable de grer les connexions IPv4
aussi bien qu'IPv6. Grer les connexions IPv4 sur une socket IPv6
suppose l'utilisation d'adresses IPv6 mappes en IPv4, ce qui est
le cas sur la plupart des plates-formes, mais pas sur FreeBSD, NetBSD
et OpenBSD, en raison des politiques systmes de ces plates-formes.
Mme sur des systmes o cette fonctionnalit n'est pas active par
dfaut, un paramtre de compilation pour configure
permet de changer ce comportement pour Apache.
Pour qu'Apache puisse grer la fois les connexions IPv4 et IPv6
avec un minimum de sockets, il faut permettre l'utilisation des adresses
IPv6 mappes en IPv4, ce qui est faisable en spcifiant l'option
de compilation --enable-v4-mapped et en utilisant la
directive gnrique Listen
comme suit :
Listen 80
Si --enable-v4-mapped a t spcifi la compilation,
les directives Listen de la configuration par dfaut sont de la forme
ci-dessus. --enable-v4-mapped est l'option de compilation
par dfaut sur toutes les plates-formes, sauf pour FreeBSD, NetBSD, et
OpenBSD, donc il est probable que votre Apache ait t compil avec
cette option.
Pour qu'Apache ne gre que les connexions IPv4, en ignorant l'ventuel
support IPv6 de la plate-forme ou d'APR, une adresse IPv4 peut tre
donne dans toutes les directives
Listen, comme dans les
exemples suivants :
Listen 0.0.0.0:80
Listen 192.170.2.1:80
Pour qu'Apache gre les connexions IPv4 et IPv6 sur des sockets
diffrents (i.e., pour ne pas accepter les adresses IPv6 mappes
en IPv4), spcifiez l'option de compilation
--disable-v4-mapped et utilisez des directives
Listen spcifiques telles que :
Listen [::]:80
Listen 0.0.0.0:80
Si le paramtre --disable-v4-mapped a t dfini
au moment de la compilation, les directives Listen de la
configuration par dfaut sont de la forme ci-dessus.
--disable-v4-mapped est l'option de
compilation par dfaut sous FreeBSD, NetBSD, et OpenBSD.
La directive Listen
n'implmente aucun Serveur Virtuel. Elle sert simplement
indiquer au serveur principal sur quels adresses et ports couter.
Dans le cas o aucune section
<VirtualHost>
n'est utilise, le serveur rpondra de la mme manire pour toutes
les requtes qu'il recevra.
Des sections
<VirtualHost>
peuvent tre utilises pour qu'Apache ragisse diffremment selon que la
requte est destine telle adresse ou tel port. Avant d'implmenter
un Serveur Virtuel au moyen de la directive VirtualHost, la directive
Listen doit tre configure pour que le serveur coute sur l'adresse
ou le port utilis. Ensuite, une section
<VirtualHost>
devrait tre utilise pour qu'Apache ragisse diffremment selon
l'adresse ou le port.
noter que si un Serveur Virtuel
<VirtualHost>
est configur sur une adresse et un port sur lesquels le serveur
n'est pas l'coute, le Serveur Virtuel ne sera pas accessible.
Serveur Apache HTTP Version 2.0
Ce document prsente les fichiers utiliss pour la configuration du serveur HTTP Apache.
| Modules Apparents | Directives Apparentes |
|---|---|
Apache se configure en positionnant des directives dans des fichiers de
configurations, au format texte. Le fichier de configuration principal
est habituellement nomm httpd.conf.
L'emplacement de ce fichier est dfini lors de la compilation
mais il est possible de le modifier en ligne de commande au lancement
d'Apache au moyen de l'option -f.
De plus, il est possible d'ajouter d'autres fichiers de configuration au
moyen de la directive Include,
qui accepte des jokers, rendant possible la lecture de multiples
fichiers de configuration. Cette directive peut tre incluse dans
n'importe quel fichier de configuration. Les changements apports
aux fichiers de configuration principale ne seront pris en compte
qu'au dmarrage d'Apache ou son redmarrage.
Le serveur lit galement un fichier contenant les types de documents
mime ; le nom de ce fichier est dfini au moyen de la directive
TypesConfig, et son nom
par dfaut est mime.types.
Les fichiers de configuration d'Apache contiennent une directive par ligne. Il est possible d'utiliser le caractre antislash "\" la fin d'une ligne pour signaler que celle-ci se continue sur la ligne suivante. Dans ce cas l'antislash doit imprativement tre le tout dernier caractre de la ligne et ne doit pas tre suivi d'espaces.
Les directives places dans les fichiers de configuration ne sont pas sensibles la casse, mais leurs arguments le sont. Les lignes commenant par le caractre "#" sont considres comme des commentaires, et sont donc ignores. Il n'est pas possible d'ajouter un commentaire en fin de ligne, aprs une directive. Les lignes vides, ainsi que les espaces prcdant les directives, sont ignors, ce qui vous permet d'indenter le fichier pour de simplifier sa lecture.
Vous pouvez tester vos fichiers de configuration sans
avoir dmarrer le serveur en utilisant la commande
apachectl configtest ou en appelant Apache
avec l'option -t.
| Modules Apparents | Directives Apparentes |
|---|---|
Apache est un serveur modulaire, ce qui signifie que le
noyau du serveur ne dispose que des fonctions des plus basiques.
Toutes les fonctions tendues sont possibles grce des modules, qui peuvent tre chargs par Apache.
Par dfaut, un certain
nombre de modules est fourni et compil avec le serveur.
Dans le cas o le serveur a t compil avec le
support dynamique des modules, il est possible de compiler
des modules part et de les charger au moyen de la directive
LoadModule. Dans le cas
contraire, il faudra recompiler tout Apache pour lui ajouter ou
lui enlever des modules. Des directives peuvent tre incluses de
faon conditionnelle selon la prsence d'un module particulier en
les positionnant dans un bloc <IfModule>.
L'option -l, passer en ligne de commande, provoque
l'affichage des modules qui sont compils dans Apache.
| Modules Apparents | Directives Apparentes |
|---|---|
Les directives positionnes dans les fichiers de configuration principaux
s'appliquent au serveur dans son ensemble. Pour spcifier des directives
spcifiques une partie du serveur, il est possible de les positionner
l'intrieur d'une des sections <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, ou <LocationMatch>.
Chacune de ces sections limite la validit des directives qu'elle
contient la partie du systme de fichier ou de l'URL qu'elle
contient. Ces sections peuvent galement se contenir les unes les autres,
ce qui permet une configuration trs fine.
Il est possible d'utiliser un seul serveur Apache pour servir plusieurs
sites web, ce qu'on appelle des Serveurs Virtuels.
Les diffrentes directives peuvent tre positionnes l'intrieur de
sections <VirtualHost>,
afin qu'elles rgulent le fonctionnement d'un site (dit virtuel)
particulier.
La plupart des directives peuvent tre positionnes dans toutes les sections prsentes ci-dessus, sauf dans certains cas. Par exemple, les directives qui contrlent la cration du processus Apache ne peuvent tre places que dans le contexte du serveur principal. Les sections possibles pour chaque directive sont dcrites au niveau du Contexte de celle-ci. Des informations plus compltes au sujet du fonctionnement des sections Directory, Location et Files sont disponibles ailleurs.
| Modules Apparents | Directives Apparentes |
|---|---|
Apache permet de dlocaliser la gestion de la configuration, au
moyen de fichiers spciaux, placs directement dans l'arborescence Web.
Ces fichiers spciaux portent le plus souvent le nom .htaccess,
mais il est bien sr possible de changer ce nom au moyen de la directive
AccessFileName.
Les directives positionnes dans un fichier .htaccess
s'appliquent au rpertoire le contenant ainsi qu' tous ses
sous-rpertoires. La syntaxe employer dans un fichier
.htaccess est identique la syntaxe des fichiers de
configuration principaux. De plus, les fichiers .htaccess
tant lus au moment de chaque requte les concernant, toute
modification de ces fichiers prend effet immdiatement sans qu'il soit
ncessaire de redmarrer le serveur.
Pour savoir si une directive peut tre place dans un fichier
.htaccess, il suffit de vrifier son Contexte. Il est possible
l'administrateur du serveur de spcifier quelles directives sont
autorises ou non dans les fichiers .htaccess, au moyen
de la directive AllowOverride,
positionne dans les fichiers de configuration principaux.
Des informations plus compltes concernant les fichiers
.htaccess sont disponible dans le
tutoriel .htaccess.
Serveur Apache HTTP Version 2.0
Apache suit les spcifications HTTP/1.1 en ce qui concerne les ngociations de contenus. Il est ainsi possible d'utiliser les informations fournies par le navigateur (prfrences de langues, jeu de caractres, encodage et types de mdias). Apache essaye aussi d'optimiser les cas des navigateurs envoyant des informations incompltes.
C'est le module mod_negotiation qui fournit
la ngociation de contenus ; ce module est inclus dans Apache
par dfaut.
Diffrentes reprsentations peuvent tre utilises pour communiquer une ressource. Par exemple, plusieurs langues peuvent tre disponibles, ou plusieurs types de mdias, voire parfois une combinaison de ces possibilits. Une mthode pour grer cela est de donner le choix au visiteur, en lui proposant un index gnral, qui lui permet par exemple de choisir sa langue. Cependant, il est souvent possible de faire ce choix de manire automatique car les navigateurs peuvent prciser avec leurs requtes, la reprsentation qu'ils prfrent recevoir. Par exemple, un navigateur pourrait spcifier qu'il prfre recevoir les informations en franais si elles sont disponibles, ou en anglais dans le cas contraire. Ce type d'information est communiqu par les navigateurs, dans les en-ttes de chaque requte. Un navigateur ne demandant que des documents en franais enverrait
Accept-Language: fr
Notez que cette prfrence ne sera gre par le serveur que s'il existe un choix de langues du ct du serveur.
Voici un exemple plus complet, o le navigateur est configur pour accepter le franais et l'anglais, mais avec une prfrence pour le franais, et pour accepter divers types de mdias, en prfrant le HTML au texte brut, et en prfrant le GIF ou le JPEG aux autres types de mdias (sans pour autant refuser ces derniers, le cas chant) :
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
Apache supporte les ngociations de contenus 'grs par
le serveur', telles que spcifies dans HTTP/1.1. Les en-ttes
Accept, Accept-Language,
Accept-Charset et Accept-Encoding
sont grs. Apache supporte galement les ngociations de
contenus 'transparentes', telles que dfinies dans les RFC
2295 et 2296. En revanche les fonctions de 'feature
negotiation' dfinies dans ces RFCs ne sont pas supportes.
On appelle ressource une entit conceptuelle identifie par un URI (RFC 2396). Le travail d'un serveur HTTP, tel Apache, est de donner un accs des reprsentations des ressources sa disposition, chaque reprsentation tant envoye sous la forme d'une squence d'octets dfinie selon un type de mdia, un jeu de caractres, un encodage, etc. tout moment, chaque ressource est associe zro, une ou plusieurs reprsentations. Si plusieurs reprsentations sont disponibles pour une ressource, on dit que cette dernire est ngociable et chacune de ses reprsentations possibles est appele une variante. Les diffrentes possibilits de choisir les variantes d'une ressource ngociable sont appeles dimensions de la ngociation.
Pour qu'Apache puisse procder la ngociation d'une ressource, il faut qu'il dispose d'informations propos de chacune des variantes. Deux mthodes sont possibles :
*.var) qui prcise explicitement les fichiers
dfinissant les variantes, ouUne table de types est un document qui est associ avec le
gestionnaire type-map (ou, dans les plus anciennes
versions d'Apache, le type mime application/x-type-map).
Notez que pour implmenter cette mthode, un 'handler' doit tre
dfini dans la configuration pour associer une extension de fichier
type-map ; ce qui est gnralement obtenu au moyen de
AddHandler type-map .var
dans le fichier de configuration du serveur.
Les fichiers de table de types portent gnralement le nom de la
ressource qu'ils dcrivent, et contiennent une entre correspondant
chaque variante possible ; ces entres sont constitues de lignes
au format d'en-ttes HTTP. Les entres de deux variantes distinctes
sont sparer par des lignes vides. Il n'est pas permis d'utiliser
des lignes vides au sein d'une entre. Il est courant de placer en
dbut de fichier une entre pour l'entit combine
dans son ensemble (bien que cela ne soit pas ncessaire, et ignor
par Apache). Un exemple de fichier de table est donn en exemple
ci-aprs. Le nom de ce fichier serait foo.var, puisque
le fichier dcrit une ressource appele foo.
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 que les fichiers de table de types sont toujours utiliss en priorit par Apache par rapport l'extension du nom du fichier, et ce mme si l'option Multiviews est active. Des variantes prsentant des qualits ingales peuvent tre indiques au moyen du paramtre de type de mdia : "qs", comme dans le cas de cette image (disponible en 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 acceptables sont comprises entre 0.000 et 1.000. Notez qu'une variante avec un qs de 0.000 ne sera jamais choisie. La valeur de qs par dfaut est de 1.0. Le paramtre qs sert indiquer la qualit de la variante, par rapport aux autres variantes disponibles, et ce indpendamment des possibilits du navigateur. Par exemple, un fichier JPEG est gnralement de meilleure qualit qu'un fichier ASCII, si les 2 documents sont destins reprsenter une photographie. Bien sr, si la ressource originale est elle-mme un fichier ASCII, la reprsentation ASCII sera considr comme de meilleure qualit que la reprsentation JPEG. La valeur de qs dpend donc de la nature de la ressource que l'on souhaite reprsenter.
La liste complte des en-ttes utilisables est disponible dans la documentation de mod_negotation.
L'option MultiViews est spcifier par rpertoire,
ce qui signifie qu'elle peut tre utilise au moyen d'une directive
Options dans une section
<Directory>,
<Location> ou
<Files>
du fichier httpd.conf, ou dans les fichiers
.htaccess ( condition que l'option AllowOverride soit paramtre pour cela).
Notez que Options All n'active pas l'option
MultiViews ; cette dernire doit tre positionne
explicitement.
Voici comment fonctionne MultiViews : supposons qu'un
serveur reoive une requte pour /some/dir/foo, que l'option
MultiViews soit active pour /some/dir,
et que le fichier /some/dir/foo n'existe
pas ; alors le serveur cherche les fichiers nomms foo.*
dans le rpertoire /some/dir, et construit une table de types
partir de ces noms de fichiers. Dans la table, chaque fichier se
voit assigner les types de mdias et les encodages de contenu
tels qu'ils seraient envoys si le client les demandait par leur
nom propre. Apache choisit alors la meilleure reprsentation
envoyer au client, en fonction de ses prfrences.
L'option MultiViews sert aussi lors du choix d'un
index, lorsque la directive DirectoryIndex est prcise.
Par exemple, si la configuration contient
DirectoryIndex index
le serveur devra choisir entre les fichiers index.html et
index.html3, dans le cas o ces deux fichiers existent. Si
aucun de ces fichiers n'existe, mais qu'un fichier index.cgi
est prsent, ce dernier sera excut par le serveur.
Si la lecture du rpertoire, un fichier est trouv
dont l'extension n'est pas reconnue par mod_mime
comme prcisant son jeu de caractres, sa langue, son type de
contenu (Content-Type) ou son encodage, alors tout dpendra de la
directive MultiViewsMatch.
Cette directive prcise en effet quels gestionnaires, filtres, et
autres types d'extensions peuvent contribuer la ngociation
MultiViews.
Aprs qu'Apache ait dfini la liste de variantes possibles pour une ressource, que ce soit via un fichier de tables de types ou partir des noms de fichiers contenus dans le rpertoire, deux mthodes peuvent tre invoques pour choisir la 'meilleure' variante qui sera envoye, pour autant qu'il en existe au moins une. Il n'est pas ncessaire de connatre ce fonctionnement pour utiliser les ngociations de contenu avec Apache ; cependant pour le lecteur intress la suite de ce document s'attache dcrire ce fonctionnement.
Il existe deux mthodes de ngociations :
| Dimension | Notes |
|---|---|
| Type de Mdia | Le navigateur prsente ses prfrences au moyen du
champ Accept de l'en-tte. chaque lment peut tre
associ un facteur de qualit. De la mme manire, la description
de la variante peut prsenter un facteur de qualit (le
paramtre "qs"). |
| Langues | Le navigateur prsente ses prfrences au moyen du champ
Accept-Language de l'en-tte. chaque lment
peut tre associ un facteur de qualit. Les diffrentes
variantes peuvent galement tre associes ou non une
ou plusieurs langues. |
| Encodage | Le navigateur prsente ses prfrences au moyen du champ
Accept-Encoding de l'en-tte. chaque lment
peut tre associ un facteur de qualit. |
| Jeu de caractres | Le navigateur prsente ses prfrences au moyen du champ
Accept-Charset de l'en-tte. chaque lment
peut tre associ un facteur de qualit. Les diffrentes
variantes peuvent se voir associer un jeu de caractres
comme type de mdia. |
Apache peut utiliser l'algorithme prsent ci-aprs pour choisir la 'meilleure' variante, si elle existe, renvoyer au navigateur. Cet algorithme n'est pas configurable. Il fonctionne de cette manire :
Accept par le facteur qualit de la source du
type de mdia de cette variante, et choisir les variantes
avec le plus grand rsultat.Accept-Language (s'il existe),
soit l'ordre des langues de la directive
LanguagePriority (si elle existe).Accept-Charset.
Le jeu de caractres ISO-8859-1 est toujours acceptable,
moins qu'il n'ait t explicitement refus. Les variantes
avec un type de mdia test/* et qui ne sont
pas explicitement associes un jeu de caractre donn
sont supposes encodes en ISO-8859-1.Vary de la rponse HTTP
est utilis pour indiquer les dimensions de la ngociation
(les navigateurs et les serveurs mandataires sont capables de
prendre en compte cette information quand il gardent une
ressource en cache). Fin des oprations.Vary est galement renseign pour prsenter les
dimensions de la ngociation.Il arrive qu'Apache modifie les facteurs de qualit par rapport
la valeur qu'ils devraient avoir en suivant strictement
l'algorithme dcrit plus haut. Ceci permet d'obtenir de meilleurs
rsultats pour grer les navigateurs qui n'envoient pas toutes
les informations ou envoient des informations errones. Ainsi,
certains navigateurs, parmi les plus rpandus du march, envoient
des en-ttes Accept qui entraneraient l'envoi de la
mauvaise variante dans de nombreux cas. Si le navigateur envoie
des informations correctes, Apache ne trichera pas sur les facteurs
de qualit.
L'en-tte de requte Accept: indique les prfrences
des types de mdias. Elle peut comporter des 'jokers' tels que
"image/*" ou "*/*", o * signifie "n'importe quoi". Ainsi, une
requte prsentant :
Accept: image/*, */*
signifierait que tout type commenant par "image/" est acceptable, comme serait acceptable tout autre type. Certains navigateurs envoient sans arrt des jokers en plus des types qu'ils peuvent effectivement grer. Par exemple :
Accept: text/html, text/plain, image/gif, image/jpeg, */*
Le but de ces informations est d'indiquer que les types explicitement cits sont les prfrs mais que le navigateur accepte galement d'autres reprsentations. En utilisant les facteurs de qualit, voici ce que devrait envoyer le navigateur :
Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
Les types explicitement cits ne prsentent pas de facteur de qualit, ils reoivent donc la valeur par dfaut de 1.0 (la plus haute valeur possible). Les jokers sont affects d'une prfrence trs basse de 0.01, si bien que les autres types ne seront utiliss que si aucune des variantes ne correspond un des types explicitement prfrs.
Si le champ d'en-tte Accept: ne
contient aucun facteur de qualit, Apache modifie
le facteur de qualit de "*/*" (s'il est prsent) en 0.01
afin d'muler le comportement souhait. Apache positionne
galement le facteur de qualit des jokers qui se prsentent
sous la forme "type/*" en 0.02 (afin que ces derniers soient
prfrs "*/*"). Si un seul ou plusieurs types de mdia de
l'en-tte Accept: prsente un facteur de qualit,
ces modifications ne sont pas effectues,
afin que les requtes des navigateurs qui envoient des
informations correctes fonctionnent comme prvu.
partir d'Apache 2.0, certaines exceptions ont t ajoutes l'algorithme de ngociation afin de retomber lgamment sur nos pattes dans les cas o la ngociation sur la langue n'aboutit pas.
Si un client demande une page du serveur, sans que ce dernier
ne puisse dterminer une page correspondant au champ
Accept-language envoy par le navigateur, le serveur
doit renvoyer une rponse parmi "Pas de Variante Acceptable"
et "Choix Multiples" au client. Afin d'viter ces messages
d'erreur, il est possible de configurer Apache pour qu'il ignore
le champ Accept-language dans ces cas et qu'il
fournisse au client un document qui ne correspond pas
explicitement sa requte. La directive
ForceLanguagePriority
peut tre utilise pour passer outre ces deux messages d'erreur
et modifier la rponse du serveur au moyen de la directive
LanguagePriority.
Le serveur va galement essayer de modifier la sous-classe
de langue si aucune correspondance n'est trouve. Par exemple,
dans le cas o un client demande des documents avec le langage
en-GB pour "British English", le protocole HTTP/1.1
n'autorise pas le serveur rpondre par un document qui serait
marqu par en. (Notez que prsenter
en-GB dans l'en-tte Accept-language
est loin d'tre pertinent, il semble trs peu probable que le
lecteur comprenne l'anglais "British" et ne comprenne pas
l'anglais "tout court". Il se trouve malheureusement que
beaucoup de navigateurs prsentent ce comportement.) Bref,
si aucune autre langue ne correspond et que le serveur
s'apprterait normalement envoyer une rponse d'erreur
"No Acceptable Variants", ou utiliser la mthode
LanguagePriority
prsente ci-avant, le serveur va ignorer la sous-classe de
langue GB et considrer que la requte
en-GB correspond bien au document en.
Implicitement, Apache ajoute la langue parente (en)
la liste des langues considres comme acceptables par le
navigateur, avec un facteur de qualit trs faible. Notez
cependant que si le client demande "en-GB; qs=0.9, fr; qs=0.8",
et que le serveur dispose de documents marqus comme "en" et
"fr", alors le document en franais sera renvoy par le serveur.
Ce comportement est ncessaire, afin de garder la compatibilit
avec HTTP/1.1 et fonctionner avec les navigateurs correctement
configurs.
Pour supporter les techniques avances de dtection de
prfrence de langues de l'utilisateur (telles que les
Cookies, ou les chemins d'URL spciaux), Apache reconnat
depuis la version 2.0.47 la variable
d'environnement prefer-language. Si cette
variable existe, et qu'elle prcise une langue valide,
mod_negociation cherchera une variante qui
y corresponde. S'il n'en trouve pas, le processus de
ngociation normal se droulera.
SetEnvIf Cookie "language=en" prefer-language=en
SetEnvIf Cookie "language=fr" prefer-language=fr
Apache complte le protocole de ngociation de contenu (RFC 2295)
comme dcrit ici. Un nouvel lment {encoding ..} est
utilis dans la liste des variantes pour nommer celles qui ne sont
disponibles que sous un encodage spcifique. L'implmentation de
l'algorithme RVSA/1.0 (RFC 2296) est tendue afin d'intgrer les
variantes encodes dans la liste, et de les proposer comme
candidates quand leur encodage est acceptable au vu de l'en-tte
Accept-Encoding. L'implmentation RVSA/1.0 ne tronque
pas les facteurs de qualit 5 dcimales avant de choisir la
meilleure des variantes.
Dans le cas o la ngociation de langues est utilise, il est possible de choisir diverses conventions de nommage, car les fichiers peuvent prsenter plus d'une extension, et l'ordre des extensions n'est normalement pas significatif (voir la documentation mod_mime pour plus de dtails).
Habituellement, un fichier a une extension pour son type MIME
(par exemple, html), parfois une extension pour son
encodage (par exemple, gz), et bien sr une extension
de langue (par exemple, en) pour distinguer les
diverses variantes.
Exemples :
Voici d'autres exemples de noms de fichiers ainsi que des liens hypertextes valides et invalides :
| Nom de 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 |
Le tableau ci-dessus montre qu'il est toujours possible de
spcifier le lien sans aucune extension dans un lien hypertexte.
(par exemple, foo). L'avantage en est qu'il est
ainsi possible de ne pas montrer le type d'un document, et de
le modifier ultrieurement, par exemple le passer de html
shtml ou cgi sans avoir besoin de
modifier aucun lien.
Pour continuer utiliser les types MIME dans les liens
(par exemple, foo.html), l'extension correspondant
la langue (ainsi que l'extension d'encodage, si elle existe)
doit tre du cot droit de l'extension du type MIME (par exemple,
foo.html.en).
Quand un cache garde en mmoire une reprsentation, il l'associe l'URL de la requte. Quand la mme URL vient tre redemande, le cache peut utiliser la reprsentation garde en mmoire, plutt que de refaire une requte au serveur. Cependant, si la ressource est ngociable cot serveur, le rsultat pourrait en tre que la rponse la premire requte mise en cache serait renvoye de faon errone. Pour prvenir ce problme, Apache marque toutes les rponses issues d'une ngociation comme "non-cachables" par les clients HTTP/1.0. Apache supporte les spcifications du protocole HTTP/1.1 en ce qui concerne la mise en cache des rponses ngocies.
Les requtes venant d'un client conforme au protocole HTTP/1.0
(qu'il s'agisse d'un navigateur ou d'un serveur cache) peuvent
tre rendues "cachables" si la directive CacheNegotiatedDocs est
utilise. Cette directive peut tre spcifie aussi bien dans
la configuration principale du serveur que dans un serveur
virtuel, et ne ncessite pas d'argument. Elle n'a aucun impact
sur les requtes des clients fonctionnant en HTTP/1.1.
Pour plus d'informations au sujet de la ngociation de contenu, voir Language Negotiation Notes de Alan J. Flavell. Notez que ce document ne sera peut-tre pas mis jour en fonction des changements intervenus dans Apache 2.0.
Serveur Apache HTTP Version 2.0
Il est possible un administrateur Apache de configurer les rponses d'Apache dans les cas o des erreurs ou problmes se prsentent.
Des rponses paramtrables peuvent tre dfinies pour tre actives au cas o le serveur dtecterait une erreur ou un problme.
Quand un script plante et gnre une rponse "500 Server Error", sa rponse peut tre remplace par un message plus convivial, ou par une redirection vers une autre URL (locale, ou sur un autre serveur).
NCSA httpd 1.3 renvoyait un message d'erreur insipide qui ne prsentait le plus souvent aucun sens ni l'utilisateur, ni dans les journaux d'enregistrement sur des symptmes causant le plantage.
Le serveur peut tre paramtr pour :
La redirection vers une autre URL peut tre utile, mais seulement si des informations peuvent tre envoyes pour expliquer/enregistrer l'erreur ou le problme plus clairement.
Pour y parvenir, Apache dfinit de nouvelles variables d'environnement CGI :
REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
image/jpeg
REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
9000/712)
REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=ooh.ahhh.com
REDIRECT_SERVER_NAME=crash.bang.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
REDIRECT_URL=/cgi-bin/buggy.pl
Notez que le prfixe REDIRECT_ est prsent pour toutes
ces variables d'environnement.
Au minimum, REDIRECT_URL et
REDIRECT_QUERY_STRING seront passes la nouvelle
URL (en supposant qu'il s'agisse d'un script CGI ou d'un
include CGI). Les autres variables ne sont dfinies que si
elles existaient avant l'apparition du problme ou de l'erreur.
Aucune de ces variables ne sera
dfinie si votre directive ErrorDocument
entrane une redirection vers un serveur externe ;
tout ce qui commence par http: est considr comme
une redirection externe, y compris si cela pointe vers le
serveur local.
Il est possible d'utiliser la directive
ErrorDocument dans les fichiers
.htaccess si AllowOverride est
paramtre pour le permettre.
Voici quelques exemples :
ErrorDocument 500 /cgi-bin/crash-recover
ErrorDocument 500 "Sorry, our script crashed. Oh dear"
ErrorDocument 500 http://xxx/
ErrorDocument 404 /Lame_excuses/not_found.html
ErrorDocument 401 /Subscription/how_to_subscribe.html
La syntaxe utiliser est :
ErrorDocument <code--3-chiffres> <action>
o l'action peut dsigner :
Le fonctionnement d'Apache vis--vis des redirections a t modifi afin que les nouvelles variables d'environnement soient disponibles pour un script ou un server-include.
Les variables CGI standard taient passes au script sur lequel pointe la redirection. Aucune indication sur la provenance de la redirection n'tait fournie.
Une srie de nouvelles variables d'environnement est
initialise pour tre passe au script sur lequel pointe
la redirection. Chacune de ces variables est munie du prfixe
REDIRECT_. Les variables d'environnement
REDIRECT_ sont cres partir des variables
d'environnement "normales", telles qu'existant avant la
redirection, mais simplement renommes au moyen du prfixe
REDIRECT_ ; ainsi par exemple HTTP_USER_AGENT
devient REDIRECT_HTTP_USER_AGENT. En plus de ces
nouvelles variables, Apache dfinit REDIRECT_URL
et REDIRECT_status pour aider le script
comprendre d'o il a t appel. L'URL d'origine et l'URL
redirige sont toutes deux ajoutes dans le journal "access".
Si ErrorDocument prcise une redirection
locale vers un script CGI, ce script devrait inclure un
champ "Status:" dans son en-tte de transmission
afin d'assurer que le client reoive bien le code d'erreur et
puisse comprendre ce qui l'a caus. Par exemple, un script
Perl ErrorDocument pourrait inclure quelque chose comme :
...
print "Content-type: text/html\n";
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
...
Un script ddi la gestion d'une erreur donne,
telle que 404 Not Found, peut bien sr
utiliser le code spcifique d'erreur et le texte associ.
Notez que le script doit envoyer l'en-tte
Status: approprie (comme par exemple
302 Found), si la rponse contient un en-tte
Location: (pour gnrer la redirection cot client).
Sans cet en-tte Status:, Location: n'aura
pas d'effet.
Apache HTTP Server Version 2.0
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:
We begin with an overview of the basic concepts behind the API, and how they are manifested in the code.
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:
SetEnv, which don't really fit well elsewhere.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:
OK.DECLINED. In this case, the server behaves in all
respects as if the handler simply hadn't been there.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.
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 */ };
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.
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 */
};
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:
*.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.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).
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.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.
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).
Stuff that should be discussed here in detail:
ap_auth_type,
ap_auth_name, and ap_requires.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).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).
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.
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).
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".
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_poolpconfptemppchildptransr->poolFor 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.
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).
More text goes here. Describe the 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.
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).
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 DefaultType 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.
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.
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:
(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.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.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.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;
}
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;
}
Apache HTTP Server Version 2.0
The allocation mechanism's within APR have a number of debugging modes that can be used to assist in finding memory problems. This document describes the modes available and gives instructions on activating them.
free()d memory and other such
nonsense.The theory is simple. The FILL_BYTE (0xa5)
is written over all malloc'd memory as we receive it, and
is written over everything that we free up during a
clear_pool. We check that blocks on the free list always
have the FILL_BYTE in them, and we check during
palloc() that the bytes still have FILL_BYTE
in them. If you ever see garbage URLs or whatnot containing lots
of 0xa5s then you know something used data that's been
freed or uninitialized.
malloc() and free()d appropriately at the
end.This is intended to be used with something like Electric
Fence or Purify to help detect memory problems. Note that if
you're using efence then you should also add in ALLOC_DEBUG.
But don't add in ALLOC_DEBUG if you're using Purify because
ALLOC_DEBUG would hide all the uninitialized read errors
that Purify can diagnose.
In particular, it causes the table_{set,add,merge}n
routines to check that their arguments are safe for the
apr_table_t they're being placed in. It currently only works
with the unix multiprocess model, but could be extended to others.
This requires a recent gcc which supports
__builtin_return_address(). The error_log output will be a
message such as:
table_push: apr_table_t created by 0x804d874 hit limit of 10
Use l *0x804d874 to find the
source that corresponds to. It indicates that a apr_table_t
allocated by a call at that address has possibly too small an
initial apr_table_t size guess.
This requires a bit of an understanding of how alloc.c works.
Not all the options outlined above can be activated at the same time. the following table gives more information.
| ALLOC DEBUG | ALLOC USE MALLOC | POOL DEBUG | MAKE TABLE PROFILE | ALLOC STATS | |
|---|---|---|---|---|---|
| ALLOC DEBUG | - | No | Yes | Yes | Yes |
| ALLOC USE MALLOC | No | - | No | No | No |
| POOL DEBUG | Yes | No | - | Yes | Yes |
| MAKE TABLE PROFILE | Yes | No | Yes | - | Yes |
| ALLOC STATS | Yes | No | Yes | Yes | - |
Additionally the debugging options are not suitable for multi-threaded versions of the server. When trying to debug with these options the server should be started in single process mode.
The various options for debugging memory are now enabled in
the apr_general.h header file in APR. The various options are
enabled by uncommenting the define for the option you wish to
use. The section of the code currently looks like this
(contained in srclib/apr/include/apr_pools.h)
/*
#define ALLOC_DEBUG
#define POOL_DEBUG
#define ALLOC_USE_MALLOC
#define MAKE_TABLE_PROFILE
#define ALLOC_STATS
*/
typedef struct ap_pool_t {
union block_hdr *first;
union block_hdr *last;
struct cleanup *cleanups;
struct process_chain *subprocesses;
struct ap_pool_t *sub_pools;
struct ap_pool_t *sub_next;
struct ap_pool_t *sub_prev;
struct ap_pool_t *parent;
char *free_first_avail;
#ifdef ALLOC_USE_MALLOC
void *allocation_list;
#endif
#ifdef POOL_DEBUG
struct ap_pool_t *joined;
#endif
int (*apr_abort)(int retcode);
struct datastruct *prog_data;
} ap_pool_t;
To enable allocation debugging simply move the #define
ALLOC_DEBUG above the start of the comments block and rebuild
the server.
In order to use the various options the server must be rebuilt after editing the header file.
Apache HTTP Server Version 2.0
Apache 2.0 uses Doxygen to document the APIs and global variables in the the code. This will explain the basics of how to document using Doxygen.
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 > 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" -> "gum"
* "/foo/bar/gum/" -> ""
* "gum" -> "gum"
* "wi\\n32\\stuff" -> "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.
Apache HTTP Server Version 2.0
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.
There are three basic filter types (each of these is actually broken down into two categories, but that comes later).
CONNECTIONAP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)PROTOCOLAP_FTYPE_PROTOCOL,
AP_FTYPE_TRANSCODE)RESOURCEPROTOCOL, 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:
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.
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. So, the first list is
r->output_filters, then r->proto_output_filters,
and finally r->connection->output_filters. These correspond
to the RESOURCE, PROTOCOL, and
CONNECTION filters respectively. 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.
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.
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.
Apache HTTP Server Version 2.0
This document is still in development and may be partially out of date.
In general, a hook function is one that Apache 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.
In order to create a new hook, four things need to be done:
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.
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)
...
)
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().
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);
}
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 tradition Apache
hook return 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.
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);
A module that wants a hook to be called needs to do two things.
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;
}
During initialisation, Apache 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, HOOK_MIDDLE);
}
mode MODULE_VAR_EXPORT my_module =
{
...
my_register_hooks /* register hooks */
};
In the example above, we didn't use the three arguments in
the hook registration function that control calling order.
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: HOOK_FIRST,
HOOK_MIDDLE and HOOK_LAST.
All modules using any particular value may be run in any
order relative to each other, but, of course, all modules using
HOOK_FIRST will be run before HOOK_MIDDLE
which are before HOOK_LAST. Modules that don't care
when they are run should use HOOK_MIDDLE. (I spaced
these out so people could do stuff like HOOK_FIRST-2
to get in slightly earlier, but is this wise? - Ben)
Note that there are two more values,
HOOK_REALLY_FIRST and 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, HOOK_MIDDLE);
}
Note that the sort used to achieve this is stable, so
ordering set by HOOK_ORDER is preserved, as far
as is possible.
Ben Laurie, 15th August 1999
Apache HTTP Server Version 2.0
Many of the documents on these Developer pages are lifted from Apache 1.3's documentation. While they are all being updated to Apache 2.0, they are in different stages of progress. Please be patient, and point out any discrepancies or errors on the developer/ pages directly to the dev@httpd.apache.org mailing list.
Apache HTTP Server Version 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.
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.
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 *papr_pool_t *plogapr_pool_t *ptempserver_rec *sA 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_ttable becomes apr_table_tThe 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_FIRSTHOOK_MIDDLEHOOK_LASTTo 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 it's name
translation, hence the use of the aszPre to define a modifier to the
position HOOK_LAST.
There are now a lot fewer stages to worry about when creating your module definition. The old defintion 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_post_config_init routines get
registeredap_hook_http_methodap_hook_open_logsap_hook_auth_checkerap_hook_access_checkerap_hook_check_user_idap_hook_default_portap_hook_pre_connectionap_hook_process_connectionap_hook_child_initap_hook_create_requestap_hook_fixupsap_hook_handlerap_hook_header_parserpost_read_request for thisap_hook_insert_filterap_hook_log_transactionap_hook_optional_fn_retrieveap_hook_post_read_requestap_hook_quick_handlerap_hook_translate_nameap_hook_type_checkerApache HTTP Server Version 2.0
Warning - this is a first (fast) draft that needs further revision!
Several changes in Apache 2.0 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
Apache 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 Apache 1.3) without introducing fragile or insecure code.
All requests pass through ap_process_request_internal()
in 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 Apache hooks which are irrelevant (and costly in terms of CPU.)
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
reprecussions.
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.
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.
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.
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.
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.
The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.
Needs Documentation. Code is:
switch (ap_satisfies(r)) {
case SATISFY_ALL:
case SATISFY_NOSPEC:
if ((access_status = ap_run_access_checker(r)) != 0) {
return decl_die(access_status, "check access", r);
}
if (ap_some_auth_required(r)) {
if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}
if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;
case SATISFY_ANY:
if (((access_status = ap_run_access_checker(r)) != 0)) {
if (!ap_some_auth_required(r)) {
return decl_die(access_status, "check access", r);
}
if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}
if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;
}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.
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.
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.
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.
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.
Apache HTTP Server Version 2.0
When using any of the threaded mpms in Apache 2.0 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 conditons that may only show up in certain conditions under heavy load.
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.
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.
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 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.
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.
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. | |
| cpdflib | ? | ||
| 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://www.mysql.com/doc/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/index.html. |
| libpng | 1.0.x | ? | |
| libpng | 1.2.x | ? | |
| libpq (PostgreSQL) | 7.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. |
Serveur Apache HTTP Version 2.0
L'ensemble de cette page pourrait se rsumer la phrase : ne jamais configurer Apache de telle sorte qu'il s'appuie sur des rsolutions DNS pour parcourir ses fichiers de configuration. Une telle configuration risque d'engendrer des problmes de fiabilit (le serveur peut ne pas dmarrer), des attaques de type dni et de vol de service (comme par exemple des utilisateurs volant les hits d'autres utilisateurs).
<VirtualHost www.abc.dom>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
Pour qu'Apache fonctionne correctement, il a absolument besoin
de deux informations pour chacun de ses serveurs virtuels :
ServerName ainsi qu'au moins une
adresse IP laquelle le serveur s'attachera pour rpondre.
L'exemple ci-dessus ne prcise pas l'adresse IP, si bien qu'Apache doit
utiliser le DNS pour trouver l'adresse de www.abc.dom.
Si, pour une raison ou une autre, le DNS ne fonctionne pas au moment
o Apache lit ses fichiers de configuration, le serveur virtuel
ne sera pas configur. Il sera incapable de rpondre
aux requtes. Jusqu' la version 1.2, Apache refusait mme de
dmarrer dans ce cas de figure.
Prenons le cas o l'adresse de www.abc.dom est 10.0.0.1
et considrons cet extrait de configuration :
<VirtualHost 10.0.0.1>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
Cette fois, Apache a besoin d'utiliser la rsolution DNS
inverse pour dterminer le nom ServerName de ce
serveur virtuel. Si cette rsolution n'aboutit pas, le serveur
virtuel sera partiellement mis hors service (jusqu' la version
1.2, Apache refusait mme de dmarrer dans ce cas de figure). Si
le serveur virtuel est un serveur bas sur un nom (name-based),
il sera totalement hors service, mais s'il s'agit d'un serveur
par IP (IP-based), il fonctionnera correctement. Cependant, dans
le cas o Apache doit gnrer une adresse complte URL en
s'appuyant sur le nom du serveur, il chouera fournir une
adresse valide.
Voici un extrait de configuration qui rsout ces deux problmes :
<VirtualHost 10.0.0.1>
ServerName www.abc.dom
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
Il existe (au moins) deux problmes possibles de dni de service.
Les versions d'Apache antrieures 1.2 ne dmarreront pas si
l'une des deux requtes DNS cites ci-dessus n'aboutissent pas pour
un de vos serveurs virtuels. Dans certains cas, les entres DNS
sont hors de contrle de l'administrateur Web ; par exemple si
abc.dom appartient un de vos clients qui a la
matrise de son propre DNS, celui-ci peut empcher votre serveur
Web (avant la version 1.2) de dmarrer, simplement en effaant
l'enregistrement www.abc.dom du DNS.
L'autre problme possible est bien plus pernicieux. Dans la configuration suivante :
<VirtualHost www.abc.dom>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
<VirtualHost www.def.dom>
ServerAdmin webguy@def.dom
DocumentRoot /www/def
</VirtualHost>
Supposons que www.abc.dom ait l'adresse 10.0.0.1,
et que www.def.dom ait l'adresse 10.0.0.2. Supposons
galement que def.com ait la main sur son DNS.
Cette configuration peut permettre def.dom de
dtourner vers son serveur tout le trafic destin
abc.dom. Pour ce faire, il doit simplement
positionner le champ DNS de www.def.dom sur 10.0.0.1,
et rien ne peut l'empcher de faire, puisqu'il a la main sur
son DNS.
Les requtes destination de 10.0.0.1 (incluant celles dont
l'URL contient http://www.abc.com/tout_et_n_importe_quoi)
seront envoyes au serveur virtuel de def.dom. Une
bonne comprhension des mcanismes internes d'Apache concernant
la gestion des serveur virtuels est requise.
Ce document explique ce
fonctionnement.
L'implmentation du support des serveur virtuels par nom depuis Apache 1.1 suppose
qu'Apache connaisse la ou les adresse(s) IP sur lesquelles le serveur
coute. Pour dterminer cette adresse, Apache utilise soit la
directive globale ServerName
(si elle est prsente), soit un appel la fonction C
gethostname (cet appel renvoie le mme rsultat
que la commande "hostname" entre sur une ligne de commande).
Une rsolution DNS est alors effectue sur l'adresse obtenue.
Pour l'instant, il n'existe aucun moyen de contourner cette
requte DNS.
Pour se prmunir du cas o cette rsolution DNS chouerait
cause de la dfaillance du serveur DNS, le nom d'hte peut tre
ajout dans /etc/hosts (il y est probablement dj).
Assurez vous que votre machine est configure pour lire ce fichier
/etc/hosts en cas de dfaillance du serveur DNS.
Pour cela, selon votre systme d'exploitation, il vous faudra configurer
/etc/resolv.conf ou /etc/nsswitch.conf.
Au cas o votre serveur n'a pas besoin de raliser des requtes
DNS pour d'autres raisons que de dmarrer Apache, il est possible
que vous puissiez vous en sortir en positionnant la variable
d'environnement HOSTRESORDER sur "local". Ceci dpend
cependant de votre systme d'exploitation et des librairies de
rsolution DNS que vous utilisez. Ceci affecte galement le
comportement des scripts CGIs, moins que vous n'utilisiez
mod_env pour contrler leur environnement. La
meilleure solution est de consulter les pages "man" ou les FAQs
spcifiques votre systme d'exploitation.
VirtualHost
Listen
ServerName
<VirtualHost _default_:*>
qui ne sert aucune pageLes problmes lis au DNS sont trs indsirables. partir d'Apache 1.2, nous avons travaill ce qu'Apache dmarre mme dans le cas o les requtes DNS chouent, mais ce n'est pas forcment la meilleure des solutions. En tous cas, obliger l'administrateur spcifier explicitement des adresses IP est galement trs indsirable sur le rseau Internet tel qu'il existe actuellement, o le nombre d'adresses IP commence manquer.
Une rponse possible au problme de vol de trafic dcrit ci-avant pourrait tre de raliser une rsolution inverse DNS sur l'adresse IP renvoye par la premire requte, et de comparer les deux noms obtenus -- lorsqu'ils sont diffrents, le serveur virtuel serait dsactiv. Ceci suppose que la configuration pour la rsolution inverse DNS soit faite correctement (c'est une chose laquelle les administrateurs DNS commencent s'habituer, en raison de l'utilisation de plus en plus rpandue des requtes DNS "double-reverse" par les serveurs FTP et les filtrages "TCP wrappers").
Dans tous les cas de figures, il ne semble pas possible de dmarrer de faon fiable un serveur virtuel quand la requte DNS a chou, moins de recourir l'utilisation d'adresses IP fixes. Des solutions partielles, telles que dsactiver des portions de la configuration selon les tches attribues au serveur Web, risquent d'tre pires que ne pas dmarrer du tout.
Au fur et mesure que HTTP/1.1 se rpand, et que les navigateurs
et les serveurs mandataires envoient l'en-tte Host,
il devient possible d'viter compltement l'utilisation de serveurs
virtuels par IP. Dans ce cas, les serveurs Web n'ont plus aucun
besoin de raliser des requtes DNS lors de leur dmarrage. Au 1er
mars 1997, ces fonctionnalits ne sont pas suffisamment dployes pour
que des serveurs Web sensibles les mettent en oeuvre (NdT : cette
remarque est aujourd'hui compltement dpasse, HTTP/1.1 est
dsormais support par l'immense majorit des navigateurs et
des serveurs mandataires).
Serveur Apache HTTP Version 2.0
Le serveur HTTP Apache est un programme modulaire permettant
l'administrateur de choisir les fonctionnalits qu'il souhaite
activer, au moyen de modules. Les modules peuvent tre intgrs
dans le programme binaire httpd au moment de la
compilation. Il est galement possible de compiler part des
modules en tant qu'objets dynamiques partags (Dynamic Shared
Objects : DSOs) existant sparment du fichier binaire principal
httpd. Les modules DSO peuvent tre compils en mme
temps que le serveur, ou aprs, au moyen de l'outil Apache pour
les extensions (apxs).
Ce document dcrit les principes de fonctionnement des modules DSO, et montre comment les utiliser.
| Modules Apparents | Directives Apparentes |
|---|---|
Le support DSO servant charger des modules Apache, est lui-mme
cod dans un module, nomm mod_so, qui doit tre
compil dans le noyau d'Apache. Ce module, ainsi que le module
core, sont les deux seuls modules qui ne peuvent
tre compils sparment d'Apache. En pratique, tous les autres
modules d'Apache peuvent tre compils en tant que modules DSO,
en passant au script configure l'option
--enable-module=shared, comme prcis dans
la documentation d'installation. Aprs
qu'un module ait t compil en DSO (nomm
mod_monmodule.so), il est possible d'utiliser la
directive de mod_so : LoadModule dans le fichier httpd.conf,
afin qu'Apache charge ledit module au dmarrage ou redmarrage du
serveur.
Afin de simplifier la cration de fichiers DSO pour les
modules Apache (et en particulier les modules tiers), un nouveau
programme de support a t ajout : apxs (APache eXtenSion). Ce programme peut tre
utilis pour crer des modules DSO en se passant de
l'arborescence source d'Apache. L'ide en est simple : lors de
l'installation d'Apache, la commande make install
positionne les fichiers d'en-ttes C d'Apache, ainsi que les
options du compilateur et les options propres la plate-forme
dans le programme apxs. Ceci permet l'utilisateur
de compiler ses modules Apache, au moyen de apxs,
sans disposer de l'arborescence source d'Apache et sans devoir
manipuler les options de compilation ou les options propres
sa plate-forme.
Voici un rsum bref des fonctionnalits DSO d'Apache 2.0 :
mod_foo.c, en tant
que DSO, sous le nom mod_foo.so :
$ ./configure --prefix=/path/to/install --enable-foo=shared
$ make install
mod_foo.c, en tant que DSO,
sous le nom mod_foo.so :
$ ./configure --add-module=module_type:/chemin/vers/le/tiers/mod_foo.c --enable-foo=shared
$ make install
$ ./configure --enable-so
$ make install
mod_foo.c, en tant que
DSO, et sans disposer de l'arborescence source d'Apache
(utilisation d'apxs) :
$ cd /chemin/vers/le/tiers
$ apxs -c mod_foo.c
$ apxs -i -a -n foo mod_foo.la
Dans tous les cas, une fois qu'un module a t compil en tant
que DSO, vous devrez utiliser la directive
LoadModule dans le
fichier httpd.conf afin qu'Apache active le module.
Sur les systmes rcents, drivs d'Unix, il existe un procd lgant, habituellement appel chargement dynamique d'objets partags DSO, permettant de compiler un morceau de code sous un format spcial, et de pouvoir le charger en temps rel dans l'espace d'adressage d'un programme excutable.
Ce chargement peut tre ralis de deux manires :
automatiquement, grce un programme systme nomm ld.so
lors du dmarrage d'un excutable, ou manuellement depuis un programme
en excution via une interface programme au moyen des appels
systmes dlopen()/dlsym() du "chargeur" Unix
Dans le premier cas, il est courant d'appeler les DSO des
bibliothques partages ou des bibliothques DSO ;
on les nomme libfoo.so ou libfoo.so.1.2.
Elles sont toutes places dans un rpertoire systme (souvent
/usr/lib) et sont lies par les programmes excutables
lors de la compilation de ces derniers, en prcisant au moment de
la compilation l'option -lfoo la commande de link
(linker command). Cette manire de procder insre les rfrences
des bibliothques dans le coeur des programmes, afin qu'au moment
du dmarrage du programme, le "chargeur" Unix puisse trouver
libfoo.so dans /usr/lib, ou bien dans
les chemins cods en dur au moyen de l'option de link -R,
ou dans un chemin configur au moyen de la variable d'environnement
LD_LIBRARY_PATH. Tous les symboles non rsolus prsents
dans le programme sont alors rsolus au moyen de DSO.
Les symboles propres au programme excutable ne sont gnralement
pas rfrencs par le DSO (puisque c'est une bibliothque de code
gnrique), et donc aucune rsolution ne doit tre suivie au del
de ce point. Le programme excutable n'a pas de travail particulier
faire pour rsoudre les symboles des DSO, puisque c'est le
"chargeur" Unix qui s'occupe de cette tche. (En ralit, le code
utilis pour invoquer ld.so fait partie du code de
dmarrage run-time, qui est li chaque programme excutable
non statique). L'avantage du chargement dynamique des bibliothques
de code gnrique est vident : le code n'est conserv qu' un seul
endroit du disque, dans une bibliothque systme comme
libc.so, ce qui permet de gagner de l'espace disque
pour chaque programme.
Dans le second cas, les DSO sont appels objets partags
ou fichiers DSO et on peut leur attribuer une extension au
choix (bien que leur nom soit habituellement foo.so).
Ces fichiers rsident normalement dans un rpertoire propre au
programme qui les utilise, et ils ne sont pas lis de manire
automatique au programme qui les appelle. Celui-ci les charge en
temps rel lors de son excution, au moyen de dlopen().
cet instant, aucune rsolution des symboles du DSO n'est ralise.
C'est le "chargeur" Unix qui ralise la tche de rsoudre les
symboles non rsolus du DSO, partir du jeu de symboles exports
par le programme et ses bibliothques DSO (en particulier, tous
les symboles de l'omniprsente libc.so). Ainsi, le DSO
gagne la connaissance des symboles du programme excutable, comme
s'il lui avait t li statiquement au dpart.
Enfin, pour tirer parti de l'API DSO, l'excutable doit rsoudre
les symboles propres au DSO via dlsym(), pour les
utiliser plus tard dans les tables de rpartition (NdT : "dispatch
tables"), etc. En d'autres termes, le programme excutable
doit rsoudre lui-mme chaque symbole pour utiliser chacun d'entre
eux. L'avantage de ce mcanisme est que les parties optionnelles
d'un programme ne sont pas charges (et donc, n'encombrent pas la
mmoire) avant que le programme n'en ait effectivement besoin.
Quand elles deviennent ncessaires, ces parties du programme peuvent
tre charges dynamiquement pour tendre les fonctionnalits du
programme.
Bien que ce fonctionnement de DSO puisse paratre simple comprendre, il existe au moins une difficult d'implmentation : permettre au DSO de rsoudre les symboles du programme quand un DSO est utilis pour tendre un programme. Pourquoi cela ? Parce que la "rsolution l'envers" des symboles DSO partir des symboles du programme excutable est contraire au principe de conception des bibliothques (o, rappelons-le, la bibliothque ne sait rien du programme qui l'utilise) ; cette "rsolution l'envers" n'est pas standardise, et n'existe pas sur toutes les plates-formes. En pratique, les symboles globaux d'un programme excutable ne sont que rarement rexports vers un DSO, et donc ne sont pas accessibles. Celui qui veut pouvoir tendre les fonctionnalits d'un programme dynamiquement, lors de l'excution, doit trouver un moyen de forcer le programme de liaison exporter tous les symboles globaux de ce programme.
L'approche par bibliothques partages est de loin la plus courante parce que c'est celle pour laquelle les mcanismes DSO ont t conus ; elle est donc utilise par presque toutes les bibliothques du systme d'exploitation. De l'autre cot, l'utilisation des objets partags reste une approche marginale.
Depuis 1998, seules quelques solutions logiciels existantes utilisent le mcanisme des DSO pour tendre leurs fonctionnalits en cours excution : Perl 5 (via son "XS mechanism" et le module DynaLoader), Netscape Server, etc. Depuis la version 1.3, Apache a rejoint ce groupe, car Apache utilise une approche modulaire pour tendre ses fonctionnalits, et utilise de manire interne des mcanismes de rpartition par liste pour lier des modules externes son noyau. Apache tait vraiment prdestin, par concept, utiliser les DSO pour charger ses modules en temps rel.
Les possibilits des DSO dcrites ci-avant prsentent les avantages suivants :
LoadModule, dans
httpd.conf, plutt que forcer les utilisateurs
recompiler le serveur pour modifier ses fonctionnalits. Par
exemple, ce mode de fonctionnement permet de faire tourner
plusieurs instances du serveur (version standard & SSL
version, version minimaliste & tendue [mod_perl, PHP3],
etc.) au moyen d'une seule installation d'Apache.apxs, ce travail est faisable sans l'arborescence
source d'Apache, et ne ncessite qu'une commande apxs -i
suivi d'un apachectl restart pour ajouter au serveur
dj en marche les fonctionnalits du module dvelopp.Les inconvnients lis l'utilisation des DSO :
ld -lfoo) sur toutes les plates-formes (par
exemple, les plates-formes bases sur a.out ne le permettent pas,
alors que celles bases sur ELF le permettent), il n'est pas possible
d'utiliser les mcanismes de DSO pour tous les modules. En d'autres
termes, les modules compils en tant que fichiers DSO sont limits
l'utilisation des symboles exports par le noyau d'Apache, par
la bibliothque C (libc) et toute autre bibliothque
dynamique ou statique utilise par le noyau d'Apache, ou par des
archives de bibliothques statiques (libfoo.a) qui
contiennent du code indpendant de la position. Les seuls moyens
d'utiliser du code l'extrieur d'un fichier DSO sont, soit de
s'assurer que le noyau d'Apache contienne une rfrence vers ce
code, soit de charger ce code au moyen de dlopen().Serveur Apache HTTP Version 2.0
Le serveur HTTP Apache permet de conserver et d'utiliser certaines informations dans des variables appeles variables d'environnement. Ces informations peuvent servir contrler divers paramtres tels que la journalisation ou le contrle d'accs. Ces variables sont galement utilises pour communiquer avec d'autres programmes, comme les scripts CGI. Ce document traite des manires de manipuler et de tirer parti de ces variables.
Bien qu'elles soient appeles variables d'environnement, il ne s'agit pas de variables d'environnement contrles par le systme d'exploitation. Ces variables sont conserves, et manipules suivant des mcanismes internes Apache. Elles sont transformes en vritables variables d'environnement (au sens systme) seulement quand elles doivent tre passes des scripts CGI ou des scripts 'Server Side Includes'. Pour manipuler l'environnement du systme d'exploitation sur lequel tourne un serveur Apache, il suffit d'utiliser les mthodes standard fournies par l'interprteur de commandes du systme d'exploitation.
| Modules Apparents | Directives Apparentes |
|---|---|
La mthode la plus simple pour dfinir une variable
d'environnement dans Apache est d'utiliser la directive
SetEnv. Les variables
peuvent galement tre charges depuis l'interprteur de
commandes partir duquel le serveur a t dmarr, au moyen
de la directive PassEnv.
Dans un but de souplesse, les directives que mod_setenvif
permet d'utiliser sont ajustables en fonction de certaines
caractristiques des requtes parvenant au serveur. Par exemple,
il est possible de dfinir une variable seulement si la requte
provient d'un certain type de navigateur (User-Agent), ou bien
si un champ Referer bien prcis est trouv. Une souplesse encore
plus grande est offerte par la directive
RewriteRule du
module mod_rewrite qui accepte le paramtre [E=...]
pour dfinir des variables d'environnement.
Enfin, la variable d'environnement UNIQUE_ID
est cre par mod_unique_id pour chaque requte, de manire
tre unique et donc reprsentative de chaque requte.
En plus de toutes les variables d'environnement dfinies dans la configuration d'Apache et celles du systme d'exploitation, les spcifications CGI demandent que certaines variables d'environnement contenant des informations propres la requte soient toujours passes aux scripts CGI et aux pages SSI.
suexec.c.| Modules Apparents | Directives Apparentes |
|---|---|
Une des principales utilisations des variables d'environnement est l'envoi d'informations aux scripts CGI. Comme prcis ci- avant, l'environnement pass aux scripts CGI contient des informations standard au sujet de la requte en plus de toutes les variables initialises au travers de la configuration d'Apache. Pour plus de dtails, consultez le tutorial CGI.
Les documents analyss par le serveur (documents SSI), grs
par le filtre INCLUDES de mod_include, peuvent
demander l'affichage de variables d'environnement au moyen de
l'lment echo, et peuvent les utiliser pour
personnaliser des pages en fonctions de certaines caractristiques
de la requte. Apache permet aussi l'utilisation de pages SSI avec
les variables d'environnement standard CGI comme discut ci-avant.
Consultez le tutorial SSI
pour plus d'informations.
Les droits d'accs au serveur peuvent tre contrls au moyen
de variables d'environnement en utilisant les directives
allow from env= et deny from env=.
Celles ci, utilises avec SetEnvIf, permettent un contrle d'accs au serveur
trs souple en fonction de caractristiques propres au client. Par
exemple, il est possible d'utiliser ces directives pour refuser
l'accs au serveur certains navigateurs (User-Agent).
Les variables d'environnement peuvent tre enregistres dans
le journal des accs ('access log') au moyen de l'option
%e de LogFormat. De plus, la dcision d'enregistrer ou
non certaines requtes peut tre prise en fonction des variables
d'environnement au moyen de la directive
CustomLog. Cette
mthode, utilise avec la directive SetEnvIf, permet un contrle trs souple de
l'enregistrement des requtes. Par exemple, il est possible de
ne pas garder de trace des requtes demandant des noms de fichiers
se terminant par gif, ou de n'enregistrer que les
requtes des clients situs hors du sous-rseau auquel appartient
le serveur.
La directive Header
peut tirer parti de l'existence ou non d'une variable
d'environnement afin de choisir d'inclure certains en-ttes
HTTP dans la rponse retourne au client. Ceci permet, par
exemple, d'envoyer un certain en-tte de rponse seulement si un
en-tte similaire a t positionn dans la requte manant du
client.
Il est possible d'utiliser une variable d'environnement pour
activer les filtres externes (grs par
mod_ext_filter au moyen de la directive
ExtFilterDefine)
grce aux options disableenv= et
enableenv=.
La forme %{ENV:...} de TestString, dans
la directive RewriteCond, permet au moteur de rcriture de
mod_rewrite d'utiliser les variables d'environnement pour
contrler les rcritures. Notez que toutes les variables
internes mod_rewrite, accessibles sans le prfixe
ENV:, ne sont pas des variables d'environnement
d'Apache. Elles sont uniquement propres mod_rewrite et ne
peuvent pas tre utilises par d'autres modules.
Certains problmes lis l'interoprabilit ont conduit la
mise en place de mcanismes spciaux, qui modifient le
fonctionnement d'Apache selon le type des clients auxquels il
rpond. Afin de garantir la plus grande souplesse possible, ces
mcanismes sont contrls par des variables d'environnement
spciales, telles que BrowserMatch, bien qu'on puisse galement utiliser
SetEnv et
PassEnv par exemple.
Ceci oblige Apache traiter la requte comme du HTTP/1.0 mme si elle a t construite sur une norme plus rcente.
Ceci provoque l'effacement de tous les champs Vary
de l'en-tte de rponse avant qu'il ne soit envoy au client.
Certains clients interprtent mal ce champ (voir
les problmes avec
certains clients), et initialiser cette variable peut
permettre de rsoudre ce problme. Cette variable requiert
galement l'utilisation de force-response-1.0.
Ceci oblige Apache n'envoyer que des rponses en HTTP/1.0 aux clients ralisant une requte en HTTP/1.0. Cette fonction a t implmente au dpart pour rsoudre un problme avec les serveurs mandataires d'AOL. Certains clients HTTP/1.0 ragissent mal quand ils reoivent une rponse en HTTP/1.1, ce qui peut poser des problmes d'interoprabilit avec eux.
Si cette variable est positionne avec une valeur de "1", le
filtre de sortie DEFLATE du module mod_deflate
se retrouve dsactiv pour les documents dont le type mime n'est
pas text/html.
Si cette variable est initialise, le filtre DEFLATE
du module mod_deflate est totalement dsactiv.
Si cette variable est initialise, les fonctions
KeepAlive sont dsactives.
Cette variable modifie le fonctionnement de
mod_negotiation. Si la variable contient un
marqueur de langue (comme en, ja ou
x-klingon), le module mod_negotiation
va tenter de fournir une rponse dans cette langue parmi les
variantes possibles. Si aucune de ces variantes n'existe, une
ngociation normale aura
lieu.
Cette variable rend le serveur plus attentif quand il doit envoyer une redirection au client. Cette variable est habituellement utilise quand un client a un problme connu pour grer les redirections. Cette variable a t implmente pour pallier un problme du logiciel WebFolders de Microsoft qui ne sait pas grer correctement les redirections vers les rpertoires via les mthodes DAV.
Existe depuis la version 2.0.40
Quand Apache envoie une redirection en rponse une requte, la rponse contient un message afficher par le client, au cas o il ne peut suivre automatiquement la redirection. Le fonctionnement par dfaut d'Apache est d'crire ce texte avec le jeu de caractre qu'il utilise, c'est dire ISO-8859-1.
Cependant, si la redirection pointe vers une page prsentant un jeu de caractres diffrent, certains navigateurs buggs utilisent le jeu de caractres du texte de la redirection, au lieu de celui de la page qu'ils affichaient. De ce fait, un texte en grec serait mal affich.
Si cette variable d'environnement est utilise, Apache n'indiquera pas le jeu de caractre dans le texte de la redirection, ce qui permet ces navigateurs d'afficher correctement la page de destination.
Il est conseill de placer les lignes suivantes dans httpd.conf afin de grer des problmes connus de certains clients.
# # Les directives ci-aprs modifient le fonctionnement standard de HTTP. # La premire directive dsactive les fonctions keepalive pour les # navigateurs disant s'appeler 'Netscape 2.x' # Il existe des problmes connus avec ces navigateurs. # La deuxime directive gre Internet Explorer 4.0b2 de Microsoft qui # n'implmente pas correctement HTTP/1.1 et qui ne supporte pas les # fonctions keepalive quand la rponse du serveur contient des codes 301 # ou 302 (redirections) # BrowserMatch "Mozilla/2" nokeepalive BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0 # # Les directives ci-dessous dsactivent HTTP/1.1 pour les navigateurs qui # violent les spcifications HTTP/1.0, en ne sachant pas analyser des # rponses basiques en HTTP/1.1. # BrowserMatch "RealPlayer 4\.0" force-response-1.0 BrowserMatch "Java/1\.0" force-response-1.0 BrowserMatch "JDK/1\.0" force-response-1.0
Cet exemple montre comment ne pas enregistrer les requtes destination d'images dans le journal des accs. Il est facile de le modifier, pour limiter l'enregistrement certains rpertoires, ou pour des requtes venant de machines prcises.
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
Cet exemple montre comment empcher le chargement d'images de votre serveur depuis des pages qui ne sont pas hberges sur celui-ci. Cette configuration n'est pas conseille, mais elle peut tre utile dans certaines circonstances. Il est suppos ici que toutes les images sont stockes dans le rpertoire /web/images.
SetEnvIf Referer "^http://www.example.com/" local_referal # Autorise les navigateurs qui n'envoient pas de champ Referer SetEnvIf Referer "^$" local_referal <Directory /web/images> Order Deny,Allow Deny from all Allow from env=local_referal </Directory>
Pour plus d'informations sur cette technique, consultez le tutorial ApacheToday Keeping Your Images from Adorning Other Sites .
Apache HTTP Server Version 2.0
The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs/2.0/faq/>.
Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.
If you are having trouble with your Apache server software, you should take the following steps:
/usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the
location on your server.Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.
USENET newsgroups:
If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.
If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,
# cd ServerRoot
# dbx httpd core
(dbx) where
(Substitute the appropriate locations for your ServerRoot
and your httpd and core files. You may have to use
gdb instead of dbx.)
With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.
Professional, commercial support for Apache is available from a number of companies.
Apache uses the sendfile syscall on platforms
where it is available in order to speed sending of responses.
Unfortunately, on some systems, Apache will detect the presence of
sendfile at compile-time, even when it does not work
properly. This happens most frequently when using network or
other non-standard file-system.
Symptoms of this problem include the above message in the error
log and zero-length responses to non-zero-sized files. The
problem generally occurs only for static files, since dynamic
content usually does not make use of sendfile.
To fix this problem, simply use the EnableSendfile directive to disable
sendfile for all or part of your server. Also see
the EnableMMAP, which can
help with similar problems.
If you get error messages related to the AcceptEx syscall
on win32, see the Win32DisableAcceptEx
directive.
Most problems with CGI scripts result in this message written in the
error log together with an Internal Server Error delivered
to the browser. A guide to helping debug this type of problem is
available in the CGI
tutorial.
Apache HTTP Server Version 2.0
Apache uses the sendfile syscall on platforms
where it is available in order to speed sending of responses.
Unfortunately, on some systems, Apache will detect the presence of
sendfile at compile-time, even when it does not work
properly. This happens most frequently when using network or
other non-standard file-system.
Symptoms of this problem include the above message in the error
log and zero-length responses to non-zero-sized files. The
problem generally occurs only for static files, since dynamic
content usually does not make use of sendfile.
To fix this problem, simply use the EnableSendfile directive to disable
sendfile for all or part of your server. Also see
the EnableMMAP, which can
help with similar problems.
If you get error messages related to the AcceptEx syscall
on win32, see the Win32DisableAcceptEx
directive.
Most problems with CGI scripts result in this message written in the
error log together with an Internal Server Error delivered
to the browser. A guide to helping debug this type of problem is
available in the CGI
tutorial.
Apache HTTP Server Version 2.0
The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs/2.0/faq/>. In addition, you can view this FAQ all in one page for easy searching and printing.
Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.
Apache HTTP Server Version 2.0
If you are having trouble with your Apache server software, you should take the following steps:
/usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the
location on your server.Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.
USENET newsgroups:
If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.
If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,
# cd ServerRoot
# dbx httpd core
(dbx) where
(Substitute the appropriate locations for your ServerRoot
and your httpd and core files. You may have to use
gdb instead of dbx.)
With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.
Professional, commercial support for Apache is available from a number of companies.
Serveur Apache HTTP Version 2.0
Ce document explique le fonctionnement des filtres avec Apache.
| Modules Apparents | Directives Apparentes |
|---|---|
On appelle filtre un processus qui s'applique aux donnes reues ou envoyes par le serveur. Les filtres en entre (input filters) servent filtrer les donnes envoyes par les clients vers le serveur, tandis que les filtres en sortie (output filters) traitent les donnes envoyes par le serveur vers un client. Il est possible d'appliquer plusieurs filtres sur un flux de donnes, et l'ordre de ces filtres est configurable.
Apache utilise des filtres en interne pour grer les grosses
requtes ou les requtes partielles (NdT sur "byte-range" :
requtes portant seulement sur une partie d'un fichier, partie
spcifie par un pointeur de dpart, et un pointeur de fin).
Certains modules permettent en plus d'utiliser des filtres en
utilisant des directives de configuration. Les filtres sont utilisables
au moyen des directives
SetInputFilter,
SetOutputFilter,
AddInputFilter,
AddOutputFilter,
RemoveInputFilter, et
RemoveOutputFilter
.
Les filtres lists ci-aprs sont fournis dans le paquetage Apache et sont utilisables par tout administrateur.
mod_includemod_deflate
Le module mod_ext_filter permet galement
d'utiliser des programmes externes Apache en tant que filtres.
Apache HTTP Server Version 2.0
This glossary defines some of the common terminology related to Apache in particular, and web serving in general. More information on each concept is provided in the links.
apxs
httpd binary that can be loaded on-demand.INCLUDES output filter
processes documents for → Server Side
Includes.www is a hostname, example.com is a domain name,
and www.example.com is a fully-qualified domain name.
cgi-script handler designates files to be processed as
→ CGIs./usr/local/apache2/conf/httpd.conf, but it may be moved using
run-time or compile-time configuration.GET, POST,
and PUT.
text/html,
image/gif, and application/octet-stream. In
HTTP, the MIME-type is transmitted in the Content-Type
→ header.httpd binary are
called static modules, while modules that are stored
separately and can be optionally loaded at run-time are called
dynamic modules or → DSOs.
Modules that are included by default
are called base modules. Many modules are available for Apache
that are not distributed as part of the Apache HTTP Server → tarball. These are referred to as
third-party modules./images/.*(jpg|gif)$". Apache uses Perl
Compatible Regular Expressions provided by the PCRE library.
tar utility.
Apache distributions are stored in compressed tar archives or using
pkzip.
http or
https, a hostname, and a path. A URL for this page is
http://httpd.apache.org/docs/2.0/glossary.html.
Serveur Apache HTTP Version 2.0
Ce document dcrit l'utilisation des gestionnaires (Handlers) Apache.
| Modules Apparents | Directives Apparentes |
|---|---|
Un Gestionnaire "handler" est une reprsentation interne Apache, qui dcrit quoi faire quand un fichier est appel. De manire gnrale, les fichiers disposent d'un gestionnaire implicite en fonction de leurs types. Le fonctionnement standard est de simplement servir le fichier tel qu'il est demand, mais certains types de fichiers peuvent tre grs diffremment.
Depuis Apache 1.1, il est possible de forcer l'utilisation des gestionnaires. Ils peuvent tre spcifis pour des fichiers prsentant une certaine extension ou prsents dans un certain rpertoire, et peuvent tre utiliss indpendamment des types des fichiers. Cette technique est avantageuse, d'abord parce que plus lgante, mais aussi parce qu'on peut ainsi associer un type de fichier et un gestionnaire un fichier. (Voir aussi : Fichiers Extensions Multiples.)
Les gestionnaires peuvent tre intgrs au serveur, ou inclus
dans un module, ou encore tre configurs au moyen de la directive
Action. Les
gestionnaires fournis par dfaut dans la distribution d'Apache
se prsentent comme suit :
default_handler() qui est le
gestionnaire utilis par dfaut pour grer les contenus
statiques. (noyau d'Apache)mod_asis)mod_cgi)mod_imap)mod_info)mod_status)mod_negotiation)Les directives ci-aprs provoquent l'excution du script
CGI footer.pl chaque requte de fichier
prsentant l'extension html.
Action add-footer /cgi-bin/footer.pl
AddHandler add-footer .html
Le travail du script CGI est alors d'envoyer le document
demand (dsign au moyen de la variable d'environnement
PATH_TRANSLATED) en lui faisant subir au pralable
les transformations dsires.
Les directives ci-aprs activent le gestionnaire
send-as-is, utilis pour grer les fichiers
qui contiennent leurs propres en-ttes HTTP. Tous les fichiers
contenus dans le rpertoire /web/htdocs/asis/
seront traits par le gestionnaire send-as-is,
sans tenir compte de leurs extensions.
<Directory /web/htdocs/asis>
SetHandler send-as-is
</Directory>
L'API d'Apache a t modifie
lors de l'implmentation des gestionnaires ; cette modification
peut se rvler intressante. Un nouvel enregistrement a t ajout
la structure request_rec :
char *handler
Pour qu'un module utilise un gestionnaire, il suffit d'affecter
r->handler avec le nom du gestionnaire avant
l'tape invoke_handler de la requte. Les
gestionnaires fonctionnent comme auparavant, bien que leurs noms
soient ncessaires au lieu d'un type de contenu. Bien qu'elle ne
soit pas ncessaire, la convention de nommage des gestionnaires
demande l'utilisation de mots spars par des tirets, ne contenant
aucun slash, afin de ne pas interfrer avec l'espace de nommage
des types de mdias.
Apache HTTP Server Version 2.0
Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.
| Related Modules | Related Directives |
|---|---|
If you have information on your web site that is sensitive or intended for only a small group of people, the techniques in this article will help you make sure that the people that see those pages are the people that you wanted to see them.
This article covers the "standard" way of protecting parts of your web site that most of you are going to use.
The directives discussed in this article will need to go
either in your main server configuration file (typically in a
<Directory> section), or
in per-directory configuration files (.htaccess files).
If you plan to use .htaccess files, you will
need to have a server configuration that permits putting
authentication directives in these files. This is done with the
AllowOverride directive, which
specifies which directives, if any, may be put in per-directory
configuration files.
Since we're talking here about authentication, you will need
an AllowOverride directive like the
following:
AllowOverride AuthConfig
Or, if you are just going to put the directives directly in your main server configuration file, you will of course need to have write permission to that file.
And you'll need to know a little bit about the directory structure of your server, in order to know where some files are kept. This should not be terribly difficult, and I'll try to make this clear when we come to that point.
Here's the basics of password protecting a directory on your server.
You'll need to create a password file. This file should be
placed somewhere not accessible from the web. This is so that
folks cannot download the password file. For example, if your
documents are served out of /usr/local/apache/htdocs you
might want to put the password file(s) in
/usr/local/apache/passwd.
To create the file, use the htpasswd utility that
came with Apache. This will be located in the bin directory
of wherever you installed Apache. To create the file, type:
htpasswd -c /usr/local/apache/passwd/passwords rbowen
htpasswd will ask you for the password, and
then ask you to type it again to confirm it:
# htpasswd -c /usr/local/apache/passwd/passwords rbowen
New password: mypassword
Re-type new password: mypassword
Adding password for user rbowen
If htpasswd is not in your path, of course
you'll have to type the full path to the file to get it to run.
On my server, it's located at
/usr/local/apache/bin/htpasswd
Next, you'll need to configure the server to request a
password and tell the server which users are allowed access.
You can do this either by editing the httpd.conf
file or using an .htaccess file. For example, if
you wish to protect the directory
/usr/local/apache/htdocs/secret, you can use the
following directives, either placed in the file
/usr/local/apache/htdocs/secret/.htaccess, or
placed in httpd.conf inside a <Directory
/usr/local/apache/apache/htdocs/secret> section.
AuthType Basic
AuthName "Restricted Files"
AuthUserFile /usr/local/apache/passwd/passwords
Require user rbowen
Let's examine each of those directives individually. The AuthType directive selects
that method that is used to authenticate the user. The most
common method is Basic, and this is the method
implemented by mod_auth. It is important to be aware,
however, that Basic authentication sends the password from the client to
the browser unencrypted. This method should therefore not be used for
highly sensitive data. Apache supports one other authentication method:
AuthType Digest. This method is implemented by mod_auth_digest and is much more secure. Only the most recent
versions of clients are known to support Digest authentication.
The AuthName directive sets
the Realm to be used in the authentication. The realm serves
two major functions. First, the client often presents this information to
the user as part of the password dialog box. Second, it is used by the
client to determine what password to send for a given authenticated
area.
So, for example, once a client has authenticated in the
"Restricted Files" area, it will automatically
retry the same password for any area on the same server that is
marked with the "Restricted Files" Realm.
Therefore, you can prevent a user from being prompted more than
once for a password by letting multiple restricted areas share
the same realm. Of course, for security reasons, the client
will always need to ask again for the password whenever the
hostname of the server changes.
The AuthUserFile
directive sets the path to the password file that we just
created with htpasswd. If you have a large number
of users, it can be quite slow to search through a plain text
file to authenticate the user on each request. Apache also has
the ability to store user information in fast database files.
The mod_auth_dbm module provides the AuthDBMUserFile directive. These
files can be created and manipulated with the dbmmanage program. Many
other types of authentication options are available from third
party modules in the Apache Modules
Database.
Finally, the Require
directive provides the authorization part of the process by
setting the user that is allowed to access this region of the
server. In the next section, we discuss various ways to use the
Require directive.
The directives above only let one person (specifically
someone with a username of rbowen) into the
directory. In most cases, you'll want to let more than one
person in. This is where the AuthGroupFile comes in.
If you want to let more than one person in, you'll need to create a group file that associates group names with a list of users in that group. The format of this file is pretty simple, and you can create it with your favorite editor. The contents of the file will look like this:
GroupName: rbowen dpitts sungo rshersey
That's just a list of the members of the group in a long line separated by spaces.
To add a user to your already existing password file, type:
htpasswd /usr/local/apache/passwd/passwords dpitts
You'll get the same response as before, but it will be
appended to the existing file, rather than creating a new file.
(It's the -c that makes it create a new password
file).
Now, you need to modify your .htaccess file to
look like the following:
AuthType Basic
AuthName "By Invitation Only"
AuthUserFile /usr/local/apache/passwd/passwords
AuthGroupFile /usr/local/apache/passwd/groups
Require group GroupName
Now, anyone that is listed in the group GroupName,
and has an entry in the password file, will be let in, if
they type the correct password.
There's another way to let multiple users in that is less specific. Rather than creating a group file, you can just use the following directive:
Require valid-user
Using that rather than the Require user rbowen
line will allow anyone in that is listed in the password file,
and who correctly enters their password. You can even emulate
the group behavior here, by just keeping a separate password
file for each group. The advantage of this approach is that
Apache only has to check one file, rather than two. The
disadvantage is that you have to maintain a bunch of password
files, and remember to reference the right one in the
AuthUserFile directive.
Because of the way that Basic authentication is specified, your username and password must be verified every time you request a document from the server. This is even if you're reloading the same page, and for every image on the page (if they come from a protected directory). As you can imagine, this slows things down a little. The amount that it slows things down is proportional to the size of the password file, because it has to open up that file, and go down the list of users until it gets to your name. And it has to do this every time a page is loaded.
A consequence of this is that there's a practical limit to how many users you can put in one password file. This limit will vary depending on the performance of your particular server machine, but you can expect to see slowdowns once you get above a few hundred entries, and may wish to consider a different authentication method at that time.
Authentication by username and password is only part of the story. Frequently you want to let people in based on something other than who they are. Something such as where they are coming from.
The Allow and
Deny directives let
you allow and deny access based on the host name, or host
address, of the machine requesting a document. The
Order directive goes
hand-in-hand with these two, and tells Apache in which order to
apply the filters.
The usage of these directives is:
Allow from address
where address is an IP address (or a partial IP address) or a fully qualified domain name (or a partial domain name); you may provide multiple addresses or domain names, if desired.
For example, if you have someone spamming your message board, and you want to keep them out, you could do the following:
Deny from 10.252.46.165
Visitors coming from that address will not be able to see the content covered by this directive. If, instead, you have a machine name, rather than an IP address, you can use that.
Deny from host.example.com
And, if you'd like to block access from an entire domain, you can specify just part of an address or domain name:
Deny from 192.168.205
Deny from phishers.example.com moreidiots.example
Deny from ke
Using Order will let you be
sure that you are actually restricting things to the group that you want
to let in, by combining a Deny
and an Allow directive:
Order deny,allow
Deny from all
Allow from dev.example.com
Listing just the Allow
directive would not do what you want, because it will let folks from that
host in, in addition to letting everyone in. What you want is to let
only those folks in.
You should also read the documentation for mod_auth
and mod_access which contain some more information
about how this all works.
Apache HTTP Server Version 2.0
| Related Modules | Related Directives |
|---|---|
The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is the simplest, and most common, way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.
In order to get your CGI programs to work properly, you'll need to have Apache configured to permit CGI execution. There are several ways to do this.
The
ScriptAlias
directive tells Apache that a particular directory is set
aside for CGI programs. Apache will assume that every file in
this directory is a CGI program, and will attempt to execute
it, when that particular resource is requested by a
client.
The ScriptAlias
directive looks like:
ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
The example shown is from your default httpd.conf
configuration file, if you installed Apache in the default
location. The ScriptAlias
directive is much like the Alias directive, which defines a URL prefix that
is to mapped to a particular directory. Alias
and ScriptAlias are usually used for
directories that are outside of the DocumentRoot directory. The difference between
Alias and ScriptAlias
is that ScriptAlias has the added meaning
that everything under that URL prefix will be considered a CGI
program. So, the example above tells Apache that any request for a
resource beginning with /cgi-bin/ should be served from
the directory /usr/local/apache2/cgi-bin/, and should be
treated as a CGI program.
For example, if the URL
http://www.example.com/cgi-bin/test.pl
is requested, Apache will attempt to execute the file
/usr/local/apache2/cgi-bin/test.pl
and return the output. Of course, the file will have to
exist, and be executable, and return output in a particular
way, or Apache will return an error message.
CGI programs are often restricted to ScriptAlias'ed directories for security reasons.
In this way, administrators can tightly control who is allowed to
use CGI programs. However, if the proper security precautions are
taken, there is no reason why CGI programs cannot be run from
arbitrary directories. For example, you may wish to let users
have web content in their home directories with the
UserDir directive.
If they want to have their own CGI programs, but don't have access to
the main cgi-bin directory, they will need to be able to
run CGI programs elsewhere.
There are two steps to allowing CGI execution in an arbitrary
directory. First, the cgi-script handler must be
activated using the AddHandler or SetHandler directive. Second,
ExecCGI must be specified in the Options directive.
You could explicitly use the Options directive, inside your main server configuration
file, to specify that CGI execution was permitted in a particular
directory:
<Directory /usr/local/apache2/htdocs/somedir>
Options +ExecCGI
</Directory>
The above directive tells Apache to permit the execution
of CGI files. You will also need to tell the server what
files are CGI files. The following AddHandler directive tells the server to treat all
files with the cgi or pl extension as CGI
programs:
AddHandler cgi-script .cgi .pl
The .htaccess tutorial
shows how to activate CGI programs if you do not have
access to httpd.conf.
To allow CGI program execution for any file ending in
.cgi in users' directories, you can use the
following configuration.
<Directory /home/*/public_html>
Options +ExecCGI
AddHandler cgi-script .cgi
</Directory>
If you wish designate a cgi-bin subdirectory of
a user's directory where everything will be treated as a CGI
program, you can use the following.
<Directory /home/*/public_html/cgi-bin>
Options ExecCGI
SetHandler cgi-script
</Directory>
There are two main differences between ``regular'' programming, and CGI programming.
First, all output from your CGI program must be preceded by a MIME-type header. This is HTTP header that tells the client what sort of content it is receiving. Most of the time, this will look like:
Content-type: text/html
Secondly, your output needs to be in HTML, or some other format that a browser will be able to display. Most of the time, this will be HTML, but occasionally you might write a CGI program that outputs a gif image, or other non-HTML content.
Apart from those two things, writing a CGI program will look a lot like any other program that you might write.
The following is an example CGI program that prints one
line to your browser. Type in the following, save it to a
file called first.pl, and put it in your
cgi-bin directory.
#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hello, World.";
Even if you are not familiar with Perl, you should be able
to see what is happening here. The first line tells Apache
(or whatever shell you happen to be running under) that this
program can be executed by feeding the file to the
interpreter found at the location /usr/bin/perl.
The second line prints the content-type declaration we
talked about, followed by two carriage-return newline pairs.
This puts a blank line after the header, to indicate the end
of the HTTP headers, and the beginning of the body. The third
line prints the string "Hello, World.". And that's the end
of it.
If you open your favorite browser and tell it to get the address
http://www.example.com/cgi-bin/first.pl
or wherever you put your file, you will see the one line
Hello, World. appear in your browser window.
It's not very exciting, but once you get that working, you'll
have a good chance of getting just about anything working.
There are four basic things that you may see in your browser when you try to access your CGI program from the web:
Content-Type set in your CGI program.Remember that the server does not run as you. That is,
when the server starts up, it is running with the permissions
of an unprivileged user - usually nobody, or
www - and so it will need extra permissions to
execute files that are owned by you. Usually, the way to give
a file sufficient permissions to be executed by nobody
is to give everyone execute permission on the file:
chmod a+x first.pl
Also, if your program reads from, or writes to, any other files, those files will need to have the correct permissions to permit this.
When you run a program from your command line, you have
certain information that is passed to the shell without you
thinking about it. For example, you have a PATH,
which tells the shell where it can look for files that you
reference.
When a program runs through the web server as a CGI program,
it may not have the same PATH. Any programs that you
invoke in your CGI program (like sendmail, for
example) will need to be specified by a full path, so that the
shell can find them when it attempts to execute your CGI
program.
A common manifestation of this is the path to the script
interpreter (often perl) indicated in the first
line of your CGI program, which will look something like:
#!/usr/bin/perl
Make sure that this is in fact the path to the interpreter.
In addition, if your CGI program depends on other environment variables, you will need to assure that those variables are passed by Apache.
Most of the time when a CGI program fails, it's because of a problem with the program itself. This is particularly true once you get the hang of this CGI stuff, and no longer make the above two mistakes. The first thing to do is to make sure that your program runs from the command line before testing it via the web server. For example, try:
cd /usr/local/apache2/cgi-bin
./first.pl
(Do not call the perl interpreter. The shell
and Apache should find the interpreter using the path information on the first line of
the script.)
The first thing you see written by your program should be
a set of HTTP headers, including the Content-Type,
followed by a blank line. If you see anything else, Apache will
return the Premature end of script headers error if
you try to run it through the server. See Writing a CGI program above for more
details.
The error logs are your friend. Anything that goes wrong generates message in the error log. You should always look there first. If the place where you are hosting your web site does not permit you access to the error log, you should probably host your site somewhere else. Learn to read the error logs, and you'll find that almost all of your problems are quickly identified, and quickly solved.
The suexec support program
allows CGI programs to be run under different user permissions,
depending on which virtual host or user home directory they are
located in. Suexec has very strict permission checking, and any
failure in that checking will result in your CGI programs
failing with Premature end of script headers.
To check if you are using suexec, run apachectl
-V and check for the location of SUEXEC_BIN.
If Apache finds an suexec binary there on startup,
suexec will be activated.
Unless you fully understand suexec, you should not be using it.
To disable suexec, simply remove (or rename) the suexec
binary pointed to by SUEXEC_BIN and then restart the
server. If, after reading about suexec,
you still wish to use it, then run suexec -V to find
the location of the suexec log file, and use that log file to
find what policy you are violating.
As you become more advanced in CGI programming, it will become useful to understand more about what's happening behind the scenes. Specifically, how the browser and server communicate with one another. Because although it's all very well to write a program that prints "Hello, World.", it's not particularly useful.
Environment variables are values that float around you as
you use your computer. They are useful things like your path
(where the computer searches for the actual file
implementing a command when you type it), your username, your
terminal type, and so on. For a full list of your normal,
every day environment variables, type
env at a command prompt.
During the CGI transaction, the server and the browser also set environment variables, so that they can communicate with one another. These are things like the browser type (Netscape, IE, Lynx), the server type (Apache, IIS, WebSite), the name of the CGI program that is being run, and so on.
These variables are available to the CGI programmer, and are half of the story of the client-server communication. The complete list of required variables is at http://hoohoo.ncsa.uiuc.edu/cgi/env.html.
This simple Perl CGI program will display all of the
environment variables that are being passed around. Two
similar programs are included in the
cgi-bin
directory of the Apache distribution. Note that some
variables are required, while others are optional, so you may
see some variables listed that were not in the official list.
In addition, Apache provides many different ways for you to
add your own environment variables
to the basic ones provided by default.
#!/usr/bin/perl
print "Content-type: text/html\n\n";
foreach $key (keys %ENV) {
print "$key --> $ENV{$key}<br>";
}
Other communication between the server and the client
happens over standard input (STDIN) and standard
output (STDOUT). In normal everyday context,
STDIN means the keyboard, or a file that a
program is given to act on, and STDOUT
usually means the console or screen.
When you POST a web form to a CGI program,
the data in that form is bundled up into a special format
and gets delivered to your CGI program over STDIN.
The program then can process that data as though it was
coming in from the keyboard, or from a file
The "special format" is very simple. A field name and its value are joined together with an equals (=) sign, and pairs of values are joined together with an ampersand (&). Inconvenient characters like spaces, ampersands, and equals signs, are converted into their hex equivalent so that they don't gum up the works. The whole data string might look something like:
name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
You'll sometimes also see this type of string appended to
a URL. When that is done, the server puts that string
into the environment variable called
QUERY_STRING. That's called a GET
request. Your HTML form specifies whether a GET
or a POST is used to deliver the data, by setting the
METHOD attribute in the FORM tag.
Your program is then responsible for splitting that string up into useful information. Fortunately, there are libraries and modules available to help you process this data, as well as handle other of the aspects of your CGI program.
When you write CGI programs, you should consider using a code library, or module, to do most of the grunt work for you. This leads to fewer errors, and faster development.
If you're writing CGI programs in Perl, modules are
available on CPAN. The most
popular module for this purpose is CGI.pm. You might
also consider CGI::Lite, which implements a minimal
set of functionality, which is all you need in most programs.
If you're writing CGI programs in C, there are a variety of
options. One of these is the CGIC library, from
http://www.boutell.com/cgic/.
There are a large number of CGI resources on the web. You can discuss CGI problems with other users on the Usenet group comp.infosystems.www.authoring.cgi. And the -servers mailing list from the HTML Writers Guild is a great source of answers to your questions. You can find out more at http://www.hwg.org/lists/hwg-servers/.
And, of course, you should probably read the CGI specification, which has all the details on the operation of CGI programs. You can find the original version at the NCSA and there is an updated draft at the Common Gateway Interface RFC project.
When you post a question about a CGI problem that you're having, whether to a mailing list, or to a newsgroup, make sure you provide enough information about what happened, what you expected to happen, and how what actually happened was different, what server you're running, what language your CGI program was in, and, if possible, the offending code. This will make finding your problem much simpler.
Note that questions about CGI problems should never be posted to the Apache bug database unless you are sure you have found a problem in the Apache source code.
Apache HTTP Server Version 2.0
.htaccess files provide a way to make configuration
changes on a per-directory basis.
| Related Modules | Related Directives |
|---|---|
.htaccess files (or "distributed configuration files")
provide a way to make configuration changes on a per-directory basis. A
file, containing one or more configuration directives, is placed in a
particular document directory, and the directives apply to that
directory, and all subdirectories thereof.
If you want to call your .htaccess file something
else, you can change the name of the file using the AccessFileName directive. For example,
if you would rather call the file .config then you
can put the following in your server configuration file:
AccessFileName .config
In general, .htaccess files use the same syntax as
the main configuration
files. What you can put in these files is determined by the
AllowOverride directive. This
directive specifies, in categories, what directives will be
honored if they are found in a .htaccess file. If a
directive is permitted in a .htaccess file, the
documentation for that directive will contain an Override section,
specifying what value must be in AllowOverride in order for that
directive to be permitted.
For example, if you look at the documentation for the AddDefaultCharset
directive, you will find that it is permitted in .htaccess
files. (See the Context line in the directive summary.) The Override line reads
FileInfo. Thus, you must have at least
AllowOverride FileInfo in order for this directive to be
honored in .htaccess files.
If you are unsure whether a particular directive is permitted in a
.htaccess file, look at the documentation for that
directive, and check the Context line for ".htaccess".
In general, you should never use .htaccess files unless
you don't have access to the main server configuration file. There is,
for example, a prevailing misconception that user authentication should
always be done in .htaccess files. This is simply not the
case. You can put user authentication configurations in the main server
configuration, and this is, in fact, the preferred way to do
things.
.htaccess files should be used in a case where the
content providers need to make configuration changes to the server on a
per-directory basis, but do not have root access on the server system.
In the event that the server administrator is not willing to make
frequent configuration changes, it might be desirable to permit
individual users to make these changes in .htaccess files
for themselves. This is particularly true, for example, in cases where
ISPs are hosting multiple user sites on a single machine, and want
their users to be able to alter their configuration.
However, in general, use of .htaccess files should be
avoided when possible. Any configuration that you would consider
putting in a .htaccess file, can just as effectively be
made in a <Directory> section in your main server
configuration file.
There are two main reasons to avoid the use of
.htaccess files.
The first of these is performance. When AllowOverride
is set to allow the use of .htaccess files, Apache will
look in every directory for .htaccess files. Thus,
permitting .htaccess files causes a performance hit,
whether or not you actually even use them! Also, the
.htaccess file is loaded every time a document is
requested.
Further note that Apache must look for .htaccess files
in all higher-level directories, in order to have a full complement of
directives that it must apply. (See section on how
directives are applied.) Thus, if a file is requested out of a
directory /www/htdocs/example, Apache must look for the
following files:
/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess
And so, for each file access out of that directory, there are 4
additional file-system accesses, even if none of those files are
present. (Note that this would only be the case if
.htaccess files were enabled for /, which
is not usually the case.)
The second consideration is one of security. You are permitting
users to modify server configuration, which may result in changes over
which you have no control. Carefully consider whether you want to give
your users this privilege. Note also that giving users less
privileges than they need will lead to additional technical support
requests. Make sure you clearly tell your users what level of
privileges you have given them. Specifying exactly what you have set
AllowOverride to, and pointing them
to the relevant documentation, will save yourself a lot of confusion
later.
Note that it is completely equivalent to put a .htaccess
file in a directory /www/htdocs/example containing a
directive, and to put that same directive in a Directory section
<Directory /www/htdocs/example> in your main server
configuration:
.htaccess file in /www/htdocs/example:
/www/htdocs/example
AddType text/example .exm
httpd.conf
file
<Directory /www/htdocs/example>
AddType text/example .exm
</Directory>
However, putting this configuration in your server configuration file will result in less of a performance hit, as the configuration is loaded once when Apache starts, rather than every time a file is requested.
The use of .htaccess files can be disabled completely
by setting the AllowOverride
directive to none:
AllowOverride None
The configuration directives found in a .htaccess file
are applied to the directory in which the .htaccess file
is found, and to all subdirectories thereof. However, it is important
to also remember that there may have been .htaccess files
in directories higher up. Directives are applied in the order that they
are found. Therefore, a .htaccess file in a particular
directory may override directives found in .htaccess files
found higher up in the directory tree. And those, in turn, may have
overridden directives found yet higher up, or in the main server
configuration file itself.
Example:
In the directory /www/htdocs/example1 we have a
.htaccess file containing the following:
Options +ExecCGI
(Note: you must have "AllowOverride Options" in effect
to permit the use of the "Options" directive in
.htaccess files.)
In the directory /www/htdocs/example1/example2 we have
a .htaccess file containing:
Options Includes
Because of this second .htaccess file, in the directory
/www/htdocs/example1/example2, CGI execution is not
permitted, as only Options Includes is in effect, which
completely overrides any earlier setting that may have been in
place.
As discussed in the documentation on Configuration Sections,
.htaccess files can override the <Directory> sections for
the corresponding directory, but will be overriden by other types
of configuration sections from the main configuration files. This
fact can be used to enforce certain configurations, even in the
presence of a liberal AllowOverride setting. For example, to
prevent script execution while allowing anything else to be set in
.htaccess you can use:
<Directory />
Allowoverride All
</Directory>
<Location />
Options +IncludesNoExec -ExecCGI
</Location>
If you jumped directly to this part of the document to find out how
to do authentication, it is important to note one thing. There is a
common misconception that you are required to use
.htaccess files in order to implement password
authentication. This is not the case. Putting authentication directives
in a <Directory>
section, in your main server configuration file, is the preferred way
to implement this, and .htaccess files should be used only
if you don't have access to the main server configuration file. See above for a discussion of when you should and should
not use .htaccess files.
Having said that, if you still think you need to use a
.htaccess file, you may find that a configuration such as
what follows may work for you.
You must have "AllowOverride AuthConfig" in effect for
these directives to be honored.
.htaccess file contents:
AuthType Basic
AuthName "Password Required"
AuthUserFile /www/passwords/password.file
AuthGroupFile /www/passwords/group.file
Require Group admins
Note that AllowOverride AuthConfig must be in effect
for these directives to have any effect.
Please see the authentication tutorial for a more complete discussion of authentication and authorization.
Another common use of .htaccess files is to enable
Server Side Includes for a particular directory. This may be done with
the following configuration directives, placed in a
.htaccess file in the desired directory:
Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml
Note that AllowOverride Options and AllowOverride
FileInfo must both be in effect for these directives to have any
effect.
Please see the SSI tutorial for a more complete discussion of server-side includes.
Finally, you may wish to use a .htaccess file to permit
the execution of CGI programs in a particular directory. This may be
implemented with the following configuration:
Options +ExecCGI
AddHandler cgi-script cgi pl
Alternately, if you wish to have all files in the given directory be considered to be CGI programs, this may be done with the following configuration:
Options +ExecCGI
SetHandler cgi-script
Note that AllowOverride Options and AllowOverride
FileInfo must both be in effect for these directives to have any
effect.
Please see the CGI tutorial for a more complete discussion of CGI programming and configuration.
When you put configuration directives in a .htaccess
file, and you don't get the desired effect, there are a number of
things that may be going wrong.
Most commonly, the problem is that AllowOverride is not
set such that your configuration directives are being honored. Make
sure that you don't have a AllowOverride None in effect
for the file scope in question. A good test for this is to put garbage
in your .htaccess file and reload. If a server error is
not generated, then you almost certainly have AllowOverride
None in effect.
If, on the other hand, you are getting server errors when trying to
access documents, check your Apache error log. It will likely tell you
that the directive used in your .htaccess file is not
permitted. Alternately, it may tell you that you had a syntax error,
which you will then need to fix.
Apache HTTP Server Version 2.0
Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.
The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is the simplest, and most common, way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.
See: CGI: Dynamic Content
.htaccess files.htaccess files provide a way to make configuration
changes on a per-directory basis. A file, containing one or more
configuration directives, is placed in a particular document directory,
and the directives apply to that directory, and all subdirectories thereof.
See: .htaccess files
SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.
On systems with multiple users, each user can be permitted to have a
web site in their home directory using the UserDir directive. Visitors
to a URL http://example.com/~username/ will get content
out of the home directory of the user "username", out of
the subdirectory specified by the UserDir directive.
Apache HTTP Server Version 2.0
On systems with multiple users, each user can be permitted to have a
web site in their home directory using the UserDir directive. Visitors
to a URL http://example.com/~username/ will get content
out of the home directory of the user "username", out of
the subdirectory specified by the UserDir directive.
Per-user web directories Setting the file path with UserDir Restricting what users are permitted to use this
feature Enabling a cgi directory for each user Allowing users to alter configuration| Related Modules | Related Directives |
|---|---|
The UserDir
directive specifies a directory out of which per-user
content is loaded. This directive may take several different forms.
If a path is given which does not start with a leading slash, it is assumed to be a directory path relative to the home directory of the specified user. Given this configuration:
UserDir public_html
the URL http://example.com/~rbowen/file.html will be
translated to the file path
/home/rbowen/public_html/file.html
If a path is given starting with a slash, a directory path will be constructed using that path, plus the username specified. Given this configuration:
UserDir /var/html
the URL http://example.com/~rbowen/file.html will be
translated to the file path /var/html/rbowen/file.html
If a path is provided which contains an asterisk (*), a path is used in which the asterisk is replaced with the username. Given this configuration:
UserDir /var/www/*/docs
the URL http://example.com/~rbowen/file.html will be
translated to the file path
/var/www/rbowen/docs/file.html
Using the syntax shown in the UserDir documentation, you can restrict what users are permitted to use this functionality:
UserDir enabled
UserDir disabled root jro fish
The configuration above will enable the feature for all users
except for those listed in the disabled statement.
You can, likewise, disable the feature for all but a few users by
using a configuration like the following:
UserDir disabled
UserDir enabled rbowen krietz
See UserDir
documentation for additional examples.
In order to give each user their own cgi-bin directory, you can use
a <Directory>
directive to make a particular subdirectory of a user's home directory
cgi-enabled.
<Directory /home/*/public_html/cgi-bin/>
Options ExecCGI
SetHandler cgi-script
</Directory>
Then, presuming that UserDir is set to
public_html, a cgi program example.cgi
could be loaded from that directory as:
http://example.com/~rbowen/cgi-bin/example.cgi
If you want to allows users to modify the server configuration in
their web space, they will need to use .htaccess files to
make these changed. Ensure that you have set AllowOverride to a
value sufficient for the directives that you want to permit the users
to modify. See the .htaccess tutorial for
additional details on how this works.
Apache HTTP Server Version 2.0
Server-side includes provide a means to add dynamic content to existing HTML documents.
| Related Modules | Related Directives |
|---|---|
This article deals with Server Side Includes, usually called simply SSI. In this article, I'll talk about configuring your server to permit SSI, and introduce some basic SSI techniques for adding dynamic content to your existing HTML pages.
In the latter part of the article, we'll talk about some of the somewhat more advanced things that can be done with SSI, such as conditional statements in your SSI directives.
SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.
The decision of when to use SSI, and when to have your page entirely generated by some program, is usually a matter of how much of the page is static, and how much needs to be recalculated every time the page is served. SSI is a great way to add small pieces of information, such as the current time. But if a majority of your page is being generated at the time that it is served, you need to look for some other solution.
To permit SSI on your server, you must have the following
directive either in your httpd.conf file, or in a
.htaccess file:
Options +Includes
This tells Apache that you want to permit files to be parsed
for SSI directives. Note that most configurations contain
multiple Options directives
that can override each other. You will probably need to apply the
Options to the specific directory where you want SSI
enabled in order to assure that it gets evaluated last.
Not just any file is parsed for SSI directives. You have to
tell Apache which files should be parsed. There are two ways to
do this. You can tell Apache to parse any file with a
particular file extension, such as .shtml, with
the following directives:
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml
One disadvantage to this approach is that if you wanted to
add SSI directives to an existing page, you would have to
change the name of that page, and all links to that page, in
order to give it a .shtml extension, so that those
directives would be executed.
The other method is to use the XBitHack directive:
XBitHack on
XBitHack
tells Apache to parse files for SSI
directives if they have the execute bit set. So, to add SSI
directives to an existing page, rather than having to change
the file name, you would just need to make the file executable
using chmod.
chmod +x pagename.html
A brief comment about what not to do. You'll occasionally
see people recommending that you just tell Apache to parse all
.html files for SSI, so that you don't have to
mess with .shtml file names. These folks have
perhaps not heard about XBitHack. The thing to
keep in mind is that, by doing this, you're requiring that
Apache read through every single file that it sends out to
clients, even if they don't contain any SSI directives. This
can slow things down quite a bit, and is not a good idea.
Of course, on Windows, there is no such thing as an execute bit to set, so that limits your options a little.
In its default configuration, Apache does not send the last modified date or content length HTTP headers on SSI pages, because these values are difficult to calculate for dynamic content. This can prevent your document from being cached, and result in slower perceived client performance. There are two ways to solve this:
XBitHack Full configuration. This
tells Apache to determine the last modified date by looking
only at the date of the originally requested file, ignoring
the modification date of any included files.mod_expires to set an explicit expiration
time on your files, thereby letting browsers and proxies
know that it is acceptable to cache them.SSI directives have the following syntax:
<!--#element attribute=value attribute=value ... -->
It is formatted like an HTML comment, so if you don't have SSI correctly enabled, the browser will ignore it, but it will still be visible in the HTML source. If you have SSI correctly configured, the directive will be replaced with its results.
The element can be one of a number of things, and we'll talk some more about most of these in the next installment of this series. For now, here are some examples of what you can do with SSI
<!--#echo var="DATE_LOCAL" -->
The echo element just spits out the value of a
variable. There are a number of standard variables, which
include the whole set of environment variables that are
available to CGI programs. Also, you can define your own
variables with the set element.
If you don't like the format in which the date gets printed,
you can use the config element, with a
timefmt attribute, to modify that formatting.
<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var="DATE_LOCAL" -->
This document last modified <!--#flastmod file="index.html" -->
This element is also subject to timefmt format
configurations.
This is one of the more common uses of SSI - to output the results of a CGI program, such as everybody's favorite, a ``hit counter.''
<!--#include virtual="/cgi-bin/counter.pl" -->
Following are some specific examples of things you can do in your HTML documents with SSI.
Earlier, we mentioned that you could use SSI to inform the user when the document was most recently modified. However, the actual method for doing that was left somewhat in question. The following code, placed in your HTML document, will put such a time stamp on your page. Of course, you will have to have SSI correctly enabled, as discussed above.
<!--#config timefmt="%A %B %d, %Y" -->
This file last modified <!--#flastmod file="ssi.shtml" -->
Of course, you will need to replace the
ssi.shtml with the actual name of the file that
you're referring to. This can be inconvenient if you're just
looking for a generic piece of code that you can paste into any
file, so you probably want to use the
LAST_MODIFIED variable instead:
<!--#config timefmt="%D" -->
This file last modified <!--#echo var="LAST_MODIFIED" -->
For more details on the timefmt format, go to
your favorite search site and look for strftime. The
syntax is the same.
If you are managing any site that is more than a few pages, you may find that making changes to all those pages can be a real pain, particularly if you are trying to maintain some kind of standard look across all those pages.
Using an include file for a header and/or a footer can
reduce the burden of these updates. You just have to make one
footer file, and then include it into each page with the
include SSI command. The include
element can determine what file to include with either the
file attribute, or the virtual
attribute. The file attribute is a file path,
relative to the current directory. That means that it
cannot be an absolute file path (starting with /), nor can it
contain ../ as part of that path. The virtual
attribute is probably more useful, and should specify a URL
relative to the document being served. It can start with a /,
but must be on the same server as the file being served.
<!--#include virtual="/footer.html" -->
I'll frequently combine the last two things, putting a
LAST_MODIFIED directive inside a footer file to be
included. SSI directives can be contained in the included file,
and includes can be nested - that is, the included file can
include another file, and so on.
In addition to being able to config the time
format, you can also config two other things.
Usually, when something goes wrong with your SSI directive, you get the message
[an error occurred while processing this directive]
If you want to change that message to something else, you
can do so with the errmsg attribute to the
config element:
<!--#config errmsg="[It appears that you don't know how to use SSI]" -->
Hopefully, end users will never see this message, because you will have resolved all the problems with your SSI directives before your site goes live. (Right?)
And you can config the format in which file
sizes are returned with the sizefmt attribute. You
can specify bytes for a full count in bytes, or
abbrev for an abbreviated number in Kb or Mb, as
appropriate.
I expect that I'll have an article some time in the coming
months about using SSI with small CGI programs. For now, here's
something else that you can do with the exec
element. You can actually have SSI execute a command using the
shell (/bin/sh, to be precise - or the DOS shell,
if you're on Win32). The following, for example, will give you
a directory listing.
<pre>
<!--#exec cmd="ls" -->
</pre>
or, on Windows
<pre>
<!--#exec cmd="dir" -->
</pre>
You might notice some strange formatting with this directive
on Windows, because the output from dir contains
the string ``<dir>'' in it, which confuses
browsers.
Note that this feature is exceedingly dangerous, as it will
execute whatever code happens to be embedded in the
exec tag. If you have any situation where users
can edit content on your web pages, such as with a
``guestbook'', for example, make sure that you have this
feature disabled. You can allow SSI, but not the
exec feature, with the IncludesNOEXEC
argument to the Options directive.
In addition to spitting out content, Apache SSI gives you the option of setting variables, and using those variables in comparisons and conditionals.
Most of the features discussed in this article are only available to you if you are running Apache 1.2 or later. Of course, if you are not running Apache 1.2 or later, you need to upgrade immediately, if not sooner. Go on. Do it now. We'll wait.
Using the set directive, you can set variables
for later use. We'll need this later in the discussion, so
we'll talk about it here. The syntax of this is as follows:
<!--#set var="name" value="Rich" -->
In addition to merely setting values literally like that, you
can use any other variable, including environment variables or the variables
discussed above (like LAST_MODIFIED, for example) to
give values to your variables. You will specify that something is
a variable, rather than a literal string, by using the dollar sign
($) before the name of the variable.
<!--#set var="modified" value="$LAST_MODIFIED" -->
To put a literal dollar sign into the value of your variable, you need to escape the dollar sign with a backslash.
<!--#set var="cost" value="\$100" -->
Finally, if you want to put a variable in the midst of a longer string, and there's a chance that the name of the variable will run up against some other characters, and thus be confused with those characters, you can place the name of the variable in braces, to remove this confusion. (It's hard to come up with a really good example of this, but hopefully you'll get the point.)
<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
Now that we have variables, and are able to set and compare
their values, we can use them to express conditionals. This
lets SSI be a tiny programming language of sorts.
mod_include provides an if,
elif, else, endif
structure for building conditional statements. This allows you
to effectively generate multiple logical pages out of one
actual page.
The structure of this conditional construct is:
<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->
A test_condition can be any sort of logical
comparison - either comparing values to one another, or testing
the ``truth'' of a particular value. (A given string is true if
it is nonempty.) For a full list of the comparison operators
available to you, see the mod_include
documentation. Here are some examples of how one might use this
construct.
In your configuration file, you could put the following line:
BrowserMatchNoCase macintosh Mac
BrowserMatchNoCase MSIE InternetExplorer
This will set environment variables ``Mac'' and ``InternetExplorer'' to true, if the client is running Internet Explorer on a Macintosh.
Then, in your SSI-enabled document, you might do the following:
<!--#if expr="${Mac} && ${InternetExplorer}" -->
Apologetic text goes here
<!--#else -->
Cool JavaScript code goes here
<!--#endif -->
Not that I have anything against IE on Macs - I just struggled for a few hours last week trying to get some JavaScript working on IE on a Mac, when it was working everywhere else. The above was the interim workaround.
Any other variable (either ones that you define, or normal
environment variables) can be used in conditional statements.
With Apache's ability to set environment variables with the
SetEnvIf directives, and other related directives,
this functionality can let you do some pretty involved dynamic
stuff without ever resorting to CGI.
SSI is certainly not a replacement for CGI, or other technologies used for generating dynamic web pages. But it is a great way to add small amounts of dynamic content to pages, without doing a lot of extra work.
^m180r 2c(9-/Cx$"P0Rޅ?:L m->0#{%L'jٓFN\@>Kn ?0 2S#P=
N@(02+t< L kĥdWغ=yQM& G bm-
mB=݂a=_a V7GcP`W^:1 ):}ThO0Ԋ Ipl9 ^,.,ǭ[!@UuHOFSr]07*гX&7-ЯT"9!B J羠M 9?K-D)tЇ@)j0e&`Q U MiT۫8GnWY[].=ٵ ҐQ~5C,$#GcKḙ9A@