Serveur HTTP Apache Version 2.5
Modules Apparentés | Directives Apparentées |
---|---|
CGI (Common Gateway Interface) définit une méthode d'interaction entre un serveur web et des programmes générateurs de contenu externes, plus souvent appelés programmes CGI ou scripts CGI. Il s'agit d'une méthode simple pour ajouter du contenu dynamique à votre site web en utilisant votre langage de programmation préféré. Ce document est une introduction à la configuration de CGI sur votre serveur web Apache, et une initiation à l'écriture de programmes CGI.
Apache doit être configuré pour permettre l'exécution des programmes CGI, pour que vos programmes CGI puissent fonctionner correctement. Il existe plusieurs méthodes pour y parvenir.
LoadModule
correspondante n'a pas été
commentée dans votre httpd.conf
. Une directive correcte
doit ressembler à ceci :
LoadModule cgid_module modules/mod_cgid.soSous Windows, ou si l'on utilise un module MPM non-threadé comme prefork, une directive correctement configurée sera du style :
LoadModule cgi_module modules/mod_cgi.so
La directive ScriptAlias
indique à Apache qu'un
répertoire particulier est dédié aux programmes CGI. Apache
considérera que tout fichier situé dans ce répertoire est un
programme CGI, et tentera de l'exécuter lorsque cette ressource
fera l'objet d'une requête client.
La directive ScriptAlias
se présente comme suit
:
ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"
Cet exemple est tiré de votre fichier de configuration
httpd.conf
par défaut, si vous avez installé Apache
dans son répertoire par défaut. La directive ScriptAlias
est similaire à la
directive Alias
, qui
définit à quel répertoire particulier doit correspondre un préfixe
d'URL. Alias
et
ScriptAlias
sont généralement utilisés pour
accéder à des répertoires situés en dehors du répertoire défini
par la directive DocumentRoot
. La différence entre
Alias
et ScriptAlias
réside dans le fait que ScriptAlias
indique
en plus que tout ce qui se trouve sous le préfixe d'URL doit être
considéré comme un programme CGI. Ainsi, l'exemple ci-dessus
indique à Apache que toute requête pour une ressource commençant
par /cgi-bin/
doit être servie depuis le répertoire
/usr/local/apache2/cgi-bin/
, et doit être traitée en
tant que programme CGI.
Par exemple, si une requête pour l'URL
http://www.example.com/cgi-bin/test.pl
est
effectuée, Apache tentera d'exécuter le fichier
/usr/local/apache2/cgi-bin/test.pl
et en renverra la
sortie. Bien entendu, le fichier doit exister, être exécutable, et
retourner sa sortie d'une manière particulière, sinon Apache
renverra un message d'erreur.
Pour des raisons de sécurité, la localisation des programmes
CGI est souvent restreinte aux
répertoires définis par ScriptAlias
. De cette manière, les administrateurs
peuvent contrôler précisément qui est autorisé à utiliser les
programmes CGI. Cependant, si les précautions adéquates quant à
la sécurité sont prises, il n'y a aucune raison pour que les
programmes CGI ne puissent pas être exécutés depuis d'autres
répertoires. Par exemple, vous pouvez autoriser les utilisateurs à
enregistrer des contenus web dans leurs répertoires home à l'aide
de la directive UserDir
. S'ils veulent mettre en
oeuvre leurs propres programmes CGI, mais n'ont pas l'autorisation
d'accès au répertoire cgi-bin
principal, ils devront
être en mesure d'exécuter ces programmes depuis un autre
répertoire.
L'autorisation d'exécution des programmes CGI dans un
répertoire arbitraire se fait en deux étapes. En premier lieu, le
gestionnaire cgi-script
doit être activé à l'aide
d'une directive AddHandler
ou SetHandler
. En second lieu,
ExecCGI
doit être spécifié dans la directive Options
.
Vous pouvez utiliser de manière explicite la directive
Options
dans le fichier de
configuration de votre serveur principal, pour indiquer que
l'exécution des programmes CGI est permise depuis un répertoire
particulier :
<Directory "/usr/local/apache2/htdocs/somedir"> Options +ExecCGI </Directory>
La directive ci-dessus indique à Apache qu'il doit permettre
l'exécution des fichiers CGI. Vous devez aussi indiquer au serveur
quels fichiers sont des fichiers CGI. La directive AddHandler
suivante indique au
serveur qu'il doit traiter tous les fichiers possédant une
extension cgi
ou pl
en tant que
programmes CGI :
AddHandler cgi-script .cgi .pl
Le tutoriel
.htaccess
montre comment activer les programmes
CGI si vous n'avez pas accès au
fichier httpd.conf
.
Pour permettre l'exécution en tant que programme CGI de tout
fichier possédant l'extension .cgi
et situé dans un
répertoire utilisateur, vous pouvez utiliser la configuration
suivante :
<Directory "/home/*/public_html"> Options +ExecCGI AddHandler cgi-script .cgi </Directory>
Pour indiquer un sous-répertoire cgi-bin
d'un
répertoire utilisateur où tout fichier sera traité en tant que
programme CGI, vous pouvez utiliser ceci :
<Directory "/home/*/public_html/cgi-bin"> Options ExecCGI SetHandler cgi-script </Directory>
Il y a deux différences principales entre la programmation "standard" et la programmation CGI.
En premier lieu, toute sortie de votre programme CGI doit être précédée d'un en-tête MIME-type. Il s'agit d'un en-tête HTTP qui indique au client quel type de contenu il reçoit. La plupart du temps, il se présente comme suit :
Content-type: text/html
En second lieu, votre sortie doit être en HTML, ou tout autre format qu'un navigateur est en mesure d'afficher. La plupart du temps, il s'agira de HTML, mais occasionnellement, vous pouvez être amené à écrire un programme CGI qui renvoie une image gif, ou un autre type de contenu non-HTML.
A part ces deux différences, un programme CGI ressemblera à tout autre programme que vous pourriez être amené à écrire.
L'exemple suivant est un exemple de programme CGI qui permet
d'afficher une ligne de caractères dans votre navigateur. Ecrivez
ce qui suit, enregistrez le dans un fichier nommé
premier.pl
, et placez le dans votre répertoire
cgi-bin
.
#!/usr/bin/perl print "Content-type: text/html\n\n"; print "Hello, World.";
Même si Perl ne vous est pas familier, vous devriez être
capable de comprendre le fonctionnement de ce programme. La
première ligne indique à Apache (ou à toute interface à partir de
laquelle le programme s'exécute) que ce programme peut être
exécuté en fournissant son fichier à l'interpréteur
/usr/bin/perl
. La seconde ligne affiche la
déclaration du type de contenu considéré, suivie de deux paires
"Retour chariot - Nouvelle ligne". Ceci a pour effet d'insérer une
ligne vide après l'en-tête pour marquer la fin des en-têtes HTTP,
et le début du corps du document. La troisième ligne affiche la
chaîne de caractères "Bonjour tout le monde . . .". Et c'est tout
ce dont vous avez besoin.
Si vous ouvrez votre navigateur favori et lui indiquez l'adresse
http://www.example.com/cgi-bin/premier.pl
ou toute autre URL correspondant à votre programme CGI, Vous
verrez la ligne Bonjour tout le monde . . .
s'afficher dans la fenêtre de votre navigateur. Ce n'est pas
extraordinaire, mais si vous y êtes parvenu, vous avez de bonnes
chances d'y parvenir pour tout autre programme plus
sophistiqué.
Vous devriez voir au moins une des quatre sorties suivantes dans votre navigateur lorsque vous essayez d'accéder à votre programme CGI depuis le web :
Content-Type
de manière appropriée dans votre
programme CGI.Souvenez-vous que le serveur ne s'exécute pas sous votre nom.
En d'autres termes, lorsque le serveur a démarré, il s'exécute
avec les droits d'un utilisateur non privilégié - en général
nobody
, ou www
- et en conséquence, il
aura besoin de droits supplémentaires pour pouvoir exécuter des
fichiers dont vous êtes le propriétaire. En général, pour qu'un
fichier ait des droits suffisants pour être exécutable par
nobody
, il suffit de lui attribuer des droits
d'exécution pour tout le monde :
chmod a+x premier.pl
En outre, si votre programme doit pouvoir accéder en lecture et/ou écriture à d'autres fichiers, ces derniers devront avoir les droits appropriés.
Lorsque vous lancez un programme depuis la ligne de commande,
certaines informations sont passées au shell sans que vous vous en
doutiez. Par exemple, la variable PATH
indique au
shell où il doit rechercher les exécutables auxquels vous faites
référence.
Lorsqu'un programme s'exécute depuis le serveur web en tant que
programme CGI, sa variable PATH
n'aura peut-être pas
la même valeur. Tout programme que vous invoquez dans votre
programme CGI ( comme par exemple sendmail
) devra
être spécifié par son chemin complet, de façon à ce que le shell
puisse le trouver lorsqu'il tentera d'exécuter votre programme
CGI.
Un exemple typique de spécification de programme est le chemin
vers l'interpréteur de script (souvent perl
) que l'on
trouve à la première ligne de votre programme CGI et qui va
ressembler à ceci :
#!/usr/bin/perl
Assurez-vous qu'il s'agit bien du chemin correct vers l'interpréteur.
Si votre programme CGI dépend de variables d'environnement non standards, vous devrez vous assurez que ces variables lui sont bien transmises par Apache.
Lorsque des en-têtes HTTP ne sont pas transmis à l'environnement, assurez-vous qu'ils sont bien formatés selon la RFC 2616, section 4.2 : les noms d'en-têtes doivent commencer par une lettre, elle-même suivie de lettres, chiffres ou traits d'union. Tout en-tête dont le nom viole cette règle sera ignoré.
La plupart des échecs dans l'exécution d'un programme CGI proviennent du programme lui-même. Ceci est particulièrement vrai lorsque ce satané programme CGI se bloque, alors que vous avez appris à ne plus commettre les deux erreurs précédentes. La première chose à faire est de vous assurer que votre programme s'exécute depuis la ligne de commande, avant de le tester à partir du serveur web. Par exemple, essayez :
cd /usr/local/apache2/cgi-bin
./premier.pl
(N'invoquez pas l'interpréteur perl
. Le shell et
Apache doivent être capable de le déterminer à partir de l'information sur le chemin située sur
la première ligne du script.)
La première chose que vous devriez voir affichée par votre
programme est un ensemble d'en-têtes HTTP, comprenant entre autres
le Content-Type
, et suivi d'une ligne vide. Si vous
voyez quoi que ce soit d'autre, Apache renverra l'erreur
Premature end of script headers
si vous tentez
d'exécuter le programme depuis le serveur. Voir Ecriture d'un programme CGI ci-dessus pour
plus de détails.
Les journaux d'erreurs sont vos amis. Toute anomalie de fonctionnement est consignée dans le journal des erreurs et c'est ici que vous devez regarder en premier en cas de problème. Si l'hébergeur de votre site ne vous donne pas accès au journal des erreurs, vous avez tout intérêt à vous tourner vers quelqu'un d'autre. Apprenez à déchiffrer les journaux d'erreurs, et vous vous apercevrez que la plupart des problèmes seront rapidement identifiés . . . et résolus.
Le programme suexec permet
d'exécuter les programmes CGI avec des droits différents selon le
serveur virtuel ou le répertoire utilisateur dans lequel ils
se situent. Suexec effectue une vérification des droits très
stricte, et toute anomalie détectée au cours de cette vérification
entraînera un echec d'exécution de votre programme CGI avec
affichage de l'erreur Premature end of script
headers
.
Pour savoir si vous pouvez utiliser suexec, tapez la commande
apachectl -V
, et regardez le chemin indiqué par
SUEXEC_BIN
. Si au démarrage d'Apache, ce dernier
trouve un exécutable suexec
dans ce chemin,
suexec sera activé.
Si vous ne maîtrisez pas le fonctionnement de suexec, il vous
est déconseillé de l'utiliser. Pour désactiver suexec, supprimer
simplement (ou renommez) l'exécutable suexec
pointé par SUEXEC_BIN
et redémarrez le serveur. Si
après une lecture de suexec, vous
décidez quand-même de l'utiliser, tapez la commande suexec
-V
pour voir où se situe le journal de suexec, et utilisez
ce dernier pour déterminer quelles règles vous violez
éventuellement.
Lorsque vos compétences en programmation CGI seront plus poussées, il s'avérera intéressant pour vous de mieux comprendre ce qui se passe en coulisse, et en particulier la manière dont le navigateur et le serveur dialoguent entre eux. En effet, bien qu'il soit tout à fait louable d'écrire un programme qui affiche "Bonjour tout le monde . . .", cela ne sert pas à grand chose.
Les variables d'environnement sont des valeurs qui gravitent
autour de vous lorsque vous utilisez votre ordinateur. Elles sont
très utiles, à l'instar de votre chemin par défaut (où votre
ordinateur va rechercher le fichier physique correspondant à la
commande que vous avez tapée), votre nom d'utilisateur, le type de
votre terminal, etc... Pour obtenir une liste complète des
variables d'environnement standards que vous utilisez tous les
jours, tapez env
dans votre interpréteur
de commandes.
Au cours de la transaction CGI, le serveur et le navigateur définissent aussi des variables d'environnement, de façon à ce qu'ils puissent communiquer entre eux. Ces variables définissent entre autre le type de navigateur (Netscape, IE, Lynx), le type de serveur (Apache, IIS, WebSite), le nom du programme CGI en cours d'exécution, etc...
Ces variables sont à la disposition du programmeur CGI, et elles constituent 50% de la communication client-serveur. La liste complète des variables requises se trouve à Common Gateway Interface RFC.
Ce programme CGI basique en Perl permet d'afficher toutes les
variables d'environnement qui sont échangées. Deux programmes
similaires sont fournis avec la distribution d'Apache et situés
dans le répertoire cgi-bin
.
Notez que certaines variables sont
obligatoires, alors que d'autres sont optionnelles, si bien que
vous verrez s'afficher certaines variables qui ne font pas partie
de la liste officielle. De plus, Apache vous propose de nombreuses
méthodes pour ajouter vos propres
variables d'environnement aux variables de base fournies par
défaut.
#!/usr/bin/perl use strict; use warnings; print "Content-type: text/html\n\n"; foreach my $key (keys %ENV) { print "$key --> $ENV{$key}<br>"; }
L'entrée standard (STDIN
) et la sortie standard
(STDOUT
) constituent d'autres voies de communication
entre le client et le serveur. Dans un contexte normal,
STDIN
correspond au clavier, ou à un fichier fourni
au programme à des fins de traitement, et STDOUT
à la
console ou à l'écran.
Lorsque vous transmettez un formulaire web à un programme CGI
par la méthode POST
, les données de ce formulaire
sont transcrites dans un format spécial et transmises à votre
programme CGI via STDIN
. Le programme peut alors les
traiter comme si elles provenaient du clavier ou d'un
fichier.
Ce "format spécial" est très simple. Un nom de champ et sa valeur sont reliés entre eux par un signe "égal" (=), et chacune de ces paires nom champ/valeur est séparée de la suivante par un "et" commercial (&). Les caractères spéciaux comme les espaces, les "et" commerciaux, et les signes "égal" sont convertis en leur équivalent hexadécimal pour éviter qu'ils ne gâchent le travail. La chaîne contenant les données doit ressembler à ceci :
name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
Vous verrez aussi parfois une chaîne de ce type accolée à une
URL. Dans ce cas, le serveur enregistre cette chaîne dans la
variable d'environnement appelée QUERY_STRING
. On a
alors affaire à une requête de type GET
. Votre
formulaire HTML indique laquelle des méthodes GET
ou
POST
est utilisée pour transmettre les données, en
définissant l'attribut METHOD
au niveau de la balise
FORM
.
Votre programme est ensuite chargé d'extraire les informations utiles de cette chaîne. Heureusement, des bibliothèques et des modules sont à votre disposition pour vous aider à traiter ces données, et à gérer les différents aspects de votre programme CGI.
Pour écrire un programme CGI, il vous est conseillé d'utiliser une bibliothèque de code, ou un module, qui effectueront une grande partie du travail de base pour vous. Ceci vous permettra de diminuer le nombre d'erreurs et d'accélérer le développement.
Si vous écrivez des programmes CGI en Perl, des modules sont à
votre disposition à CPAN. A ce
sujet, le module le plus populaire est CGI.pm
. Vous
pouvez aussi essayer CGI::Lite
, qui implémente les
fonctionnalités strictement nécessaires, mais suffisantes pour
la majorité des programmes.
Si vous écrivez des programmes CGI en C, vous disposez de
nombreuses options. L'une d'elles est la bibliothèque
CGIC
de http://www.boutell.com/cgic/.
La spécification CGI actuelle est disponible dans la Common Gateway Interface RFC.
Lorsque vous postez une question à propos d'un problème CGI que vous rencontrez, que ce soit dans une liste de diffusion ou dans un newsgroup, faites en sorte de fournir suffisamment d'informations sur le problème rencontré, ce que vous attendiez exactement, et en quoi ce qui se produit est réellement différent de ce que vous attendiez, quel serveur vous utilisez, en quel langage votre programme CGI a été écrit, et, si possible, son code source. Ceci permettra une résolution plus aisée de votre problème.
Notez que les questions à propos de problèmes CGI ne doivent jamais être postées dans la base de données de bogues d'Apache, à moins que vous ne soyez sûr d'avoir trouvé un problème dans le code source d'Apache.