Tutoriel Apache : Contenu dynamique basé sur CGI

Langues Disponibles: en | + es | + fr | + ja | + ko

Introduction
Configurer Apache pour autoriser CGI
Ecrire un programme CGI
Mais ça ne marche toujours pas !
Que se passe-t-il en coulisse
Bibliothèques et modules CGI
Pour plus d'informations

Voir aussi

Commentaires

Introduction

Modules Apparentés	Directives Apparentées
`mod_alias` `mod_cgi` `mod_cgid`	`AddHandler` `Options` `ScriptAlias`

+ + + + +

CGI (Common Gateway Interface) définit une méthode d'interaction + entre un serveur web et des programmes générateurs de contenu + externes, plus souvent appelés programmes CGI ou scripts CGI. + Il s'agit d'une méthode simple pour ajouter du contenu dynamique à votre site + web en utilisant votre langage de programmation préféré. + Ce document est une introduction à la configuration de CGI sur votre + serveur web Apache, et une initiation à l'écriture de programmes + CGI.

Configurer Apache pour autoriser CGI

+ + +

Apache doit être configuré pour permettre l'exécution des + programmes CGI, pour que vos programmes CGI puissent fonctionner + correctement. Il existe plusieurs méthodes pour y parvenir.

+ +

Note: si Apache a été compilé avec le support + des modules partagés (DSO), vous devez vous assurer que le module CGI est + chargé ; vous devez pour cela vérifier que la directive LoadModule correspondante n'a pas été + commentée dans votre httpd.conf. Une directive correcte + doit ressembler à ceci : + +

LoadModule cgid_module modules/mod_cgid.so

+ + + + Sous Windows, ou si l'on utilise un module MPM non-threadé comme prefork, + une directive correctement configurée sera du style : + +

LoadModule cgi_module modules/mod_cgi.so

+ + +

ScriptAlias

+ + +

La directive ScriptAlias indique à Apache qu'un + répertoire particulier est dédié aux programmes CGI. Apache + considérera que tout fichier situé dans ce répertoire est un + programme CGI, et tentera de l'exécuter lorsque cette ressource + fera l'objet d'une requête client.

+ +

La directive ScriptAlias se présente comme suit + :

+ +

ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/"

+ + +

Cet exemple est tiré de votre fichier de configuration + httpd.conf par défaut, si vous avez installé Apache + dans son répertoire par défaut. La directive ScriptAlias est similaire à la + directive Alias, qui + définit à quel répertoire particulier doit correspondre un préfixe + d'URL. Alias et + ScriptAlias sont généralement utilisés pour + accéder à des répertoires situés en dehors du répertoire défini + par la directive DocumentRoot. La différence entre + Alias et ScriptAlias + réside dans le fait que ScriptAlias indique + en plus que tout ce qui se trouve sous le préfixe d'URL doit être + considéré comme un programme CGI. Ainsi, l'exemple ci-dessus + indique à Apache que toute requête pour une ressource commençant + par /cgi-bin/ doit être servie depuis le répertoire + /usr/local/apache2/cgi-bin/, et doit être traitée en + tant que programme CGI.

+ +

Par exemple, si une requête pour l'URL + http://www.example.com/cgi-bin/test.pl est + effectuée, Apache tentera d'exécuter le fichier + /usr/local/apache2/cgi-bin/test.pl et en renverra la + sortie. Bien entendu, le fichier doit exister, être exécutable, et + retourner sa sortie d'une manière particulière, sinon Apache + renverra un message d'erreur.

+ + +

CGI en dehors des répertoires ScripAlias

+ + +

Pour des raisons de sécurité, la localisation des programmes + CGI est souvent restreinte aux + répertoires définis par ScriptAlias. De cette manière, les administrateurs + peuvent contrôler précisément qui est autorisé à utiliser les + programmes CGI. Cependant, si les précautions adéquates quant à + la sécurité sont prises, il n'y a aucune raison pour que les + programmes CGI ne puissent pas être exécutés depuis d'autres + répertoires. Par exemple, vous pouvez autoriser les utilisateurs à + enregistrer des contenus web dans leurs répertoires home à l'aide + de la directive UserDir. S'ils veulent mettre en + oeuvre leurs propres programmes CGI, mais n'ont pas l'autorisation + d'accès au répertoire cgi-bin principal, ils devront + être en mesure d'exécuter ces programmes depuis un autre + répertoire.

+ +

L'autorisation d'exécution des programmes CGI dans un + répertoire arbitraire se fait en deux étapes. En premier lieu, le + gestionnaire cgi-script doit être activé à l'aide + d'une directive AddHandler ou SetHandler. En second lieu, + ExecCGI doit être spécifié dans la directive Options.

+ + +

Utilisation d'options explicites pour permettre l'exécution + des programmes CGI

+ + +

Vous pouvez utiliser de manière explicite la directive + Options dans le fichier de + configuration de votre serveur principal, pour indiquer que + l'exécution des programmes CGI est permise depuis un répertoire + particulier :

+ +

<Directory "/usr/local/apache2/htdocs/somedir">
+    Options +ExecCGI
+</Directory>

+ + +

La directive ci-dessus indique à Apache qu'il doit permettre + l'exécution des fichiers CGI. Vous devez aussi indiquer au serveur + quels fichiers sont des fichiers CGI. La directive AddHandler suivante indique au + serveur qu'il doit traiter tous les fichiers possédant une + extension cgi ou pl en tant que + programmes CGI :

+ +

AddHandler cgi-script .cgi .pl

+ + + +

Fichiers .htaccess

+ + +

Le tutoriel + .htaccess montre comment activer les programmes + CGI si vous n'avez pas accès au + fichier httpd.conf.

+ + +

Répertoires utilisateurs

+ + +

Pour permettre l'exécution en tant que programme CGI de tout + fichier possédant l'extension .cgi et situé dans un + répertoire utilisateur, vous pouvez utiliser la configuration + suivante :

+ +

<Directory "/home/*/public_html">
+    Options +ExecCGI
+    AddHandler cgi-script .cgi
+</Directory>

+ + +

Pour indiquer un sous-répertoire cgi-bin d'un + répertoire utilisateur où tout fichier sera traité en tant que + programme CGI, vous pouvez utiliser ceci :

+ +

<Directory "/home/*/public_html/cgi-bin">
+    Options ExecCGI
+    SetHandler cgi-script
+</Directory>

+ + + + +

Ecrire un programme CGI

+ + +

Il y a deux différences principales entre la programmation + "standard" et la programmation CGI.

+ +

En premier lieu, toute sortie de votre programme CGI doit être + précédée d'un en-tête MIME-type. Il s'agit d'un + en-tête HTTP qui indique au client quel type de contenu il reçoit. + La plupart du temps, il se présente comme suit :

+ +

+ Content-type: text/html +

+ +

En second lieu, votre sortie doit être en HTML, ou tout autre + format qu'un navigateur est en mesure d'afficher. La plupart du + temps, il s'agira de HTML, mais occasionnellement, vous pouvez être + amené à écrire un programme CGI qui renvoie une image gif, ou un + autre type de contenu non-HTML.

+ +

A part ces deux différences, un programme CGI ressemblera à tout + autre programme que vous pourriez être amené à écrire.

+ +

Votre premier programme CGI

+ + +

L'exemple suivant est un exemple de programme CGI qui permet + d'afficher une ligne de caractères dans votre navigateur. Ecrivez + ce qui suit, enregistrez le dans un fichier nommé + premier.pl, et placez le dans votre répertoire + cgi-bin.

+ +

#!/usr/bin/perl
+print "Content-type: text/html\n\n";
+print "Hello, World.";

+ + +

Même si Perl ne vous est pas familier, vous devriez être + capable de comprendre le fonctionnement de ce programme. La + première ligne indique à Apache (ou à toute interface à partir de + laquelle le programme s'exécute) que ce programme peut être + exécuté en fournissant son fichier à l'interpréteur + /usr/bin/perl. La seconde ligne affiche la + déclaration du type de contenu considéré, suivie de deux paires + "Retour chariot - Nouvelle ligne". Ceci a pour effet d'insérer une + ligne vide après l'en-tête pour marquer la fin des en-têtes HTTP, + et le début du corps du document. La troisième ligne affiche la + chaîne de caractères "Bonjour tout le monde . . .". Et c'est tout + ce dont vous avez besoin.

+ +

Si vous ouvrez votre navigateur favori et lui indiquez + l'adresse

+ +

+ http://www.example.com/cgi-bin/premier.pl +

+ +

ou toute autre URL correspondant à votre programme CGI, Vous + verrez la ligne Bonjour tout le monde . . . + s'afficher dans la fenêtre de votre navigateur. Ce n'est pas + extraordinaire, mais si vous y êtes parvenu, vous avez de bonnes + chances d'y parvenir pour tout autre programme plus + sophistiqué.

+ +

Mais ça ne marche toujours pas !

+ + +

Vous devriez voir au moins une des quatre sorties suivantes dans + votre navigateur lorsque vous essayez d'accéder à votre programme + CGI depuis le web :

+ +

Le flux de sortie de votre programme CGI: Impeccable ! Cela signifie que tout fonctionne correctement. + Si la sortie est correcte mais n'est pas traitée correctement par + le navigateur, assurez-vous d'avoir défini + Content-Type de manière appropriée dans votre + programme CGI.
Le code source de votre programme CGI ou un message "POST + Method Not Allowed": Cela signifie que vous n'avez pas configuré Apache de manière + à ce qu'il puisse traiter votre programme CGI. Relisez la section + sur la configuration d'Apache, et + essayez de trouver votre erreur.
Un message commençant par "Forbidden": Ce type de message est révélateur d'un problème de + droits. Consultez le journal des erreurs + d'Apache et la section ci-dessous sur les droits des fichiers.
Un message contenant "Internal Server Error": Si vous consultez le journal des erreurs + d'Apache, vous y trouverez probablement des messages du type + "Premature end of script headers" (Fin prématurée des en-têtes de + script), éventuellement accompagnés d'un message d'erreur généré + par votre programme CGI. Dans ce cas, il va vous falloir lire + chacune des sections ci-dessous pour déterminer ce qui empêche + votre programme CGI de générer les en-têtes appropriés.

+ +

Droits des fichiers

+ + +

Souvenez-vous que le serveur ne s'exécute pas sous votre nom. + En d'autres termes, lorsque le serveur a démarré, il s'exécute + avec les droits d'un utilisateur non privilégié - en général + nobody, ou www - et en conséquence, il + aura besoin de droits supplémentaires pour pouvoir exécuter des + fichiers dont vous êtes le propriétaire. En général, pour qu'un + fichier ait des droits suffisants pour être exécutable par + nobody, il suffit de lui attribuer des droits + d'exécution pour tout le monde :

+ +

+ chmod a+x premier.pl +

+ +

En outre, si votre programme doit pouvoir accéder en lecture + et/ou écriture à d'autres fichiers, ces derniers devront avoir les + droits appropriés.

+ + + +

Chemin des exécutables (PATH) et variables + d'environnement

+ + +

Lorsque vous lancez un programme depuis la ligne de commande, + certaines informations sont passées au shell sans que vous vous en + doutiez. Par exemple, la variable PATH indique au + shell où il doit rechercher les exécutables auxquels vous faites + référence.

+ +

Lorsqu'un programme s'exécute depuis le serveur web en tant que + programme CGI, sa variable PATH n'aura peut-être pas + la même valeur. Tout programme que vous invoquez dans votre + programme CGI ( comme par exemple sendmail) devra + être spécifié par son chemin complet, de façon à ce que le shell + puisse le trouver lorsqu'il tentera d'exécuter votre programme + CGI.

+ +

Un exemple typique de spécification de programme est le chemin + vers l'interpréteur de script (souvent perl) que l'on + trouve à la première ligne de votre programme CGI et qui va + ressembler à ceci :

+ +

#!/usr/bin/perl

+ + +

Assurez-vous qu'il s'agit bien du chemin correct vers + l'interpréteur.

+ +

+ Lors de l'édition de scripts CGI sous Windows, il se peut que des + caractères de fin de ligne soient ajoutés au chemin de + l'interpréteur. Assurez-vous donc que les fichiers sont bien + transmis au serveur en mode ASCII. Dans le cas contraire, l'OS + pourra envoyer des avertissements "Command not found" à cause des + caractères de fin de ligne non reconnus car considérés comme + faisant partie du nom de fichier de l'interpréteur. +

+ + + +

Variables d'environnement manquantes

+ + +

Si votre programme CGI dépend de variables + d'environnement non standards, vous devrez vous assurez que + ces variables lui sont bien transmises par Apache.

+ +

Lorsque des en-têtes HTTP ne sont pas transmis à + l'environnement, assurez-vous qu'ils sont bien formatés selon la + RFC 2616, section + 4.2 : les noms d'en-têtes doivent commencer par une lettre, + elle-même suivie de lettres, chiffres ou traits d'union. Tout + en-tête dont le nom viole cette règle sera ignoré.

+ + + +

Erreurs inhérentes au programme

+ + +

La plupart des échecs dans l'exécution d'un programme CGI + proviennent du programme lui-même. Ceci est particulièrement vrai + lorsque ce satané programme CGI se bloque, alors que vous avez + appris à ne plus commettre les deux erreurs précédentes. La + première chose à faire est de vous assurer que votre programme + s'exécute depuis la ligne de commande, avant de le tester à partir + du serveur web. Par exemple, essayez :

+ +

+ cd /usr/local/apache2/cgi-bin + ./premier.pl +

+ +

(N'invoquez pas l'interpréteur perl. Le shell et + Apache doivent être capable de le déterminer à partir de l'information sur le chemin située sur + la première ligne du script.)

+ +

La première chose que vous devriez voir affichée par votre + programme est un ensemble d'en-têtes HTTP, comprenant entre autres + le Content-Type, et suivi d'une ligne vide. Si vous + voyez quoi que ce soit d'autre, Apache renverra l'erreur + Premature end of script headers si vous tentez + d'exécuter le programme depuis le serveur. Voir Ecriture d'un programme CGI ci-dessus pour + plus de détails.

+ + +

Journalisation des erreurs

+ + +

Les journaux d'erreurs sont vos amis. Toute anomalie de + fonctionnement est consignée dans le journal des erreurs et c'est + ici que vous devez regarder en premier en cas de problème. Si + l'hébergeur de votre site ne vous donne pas accès au journal des + erreurs, vous avez tout intérêt à vous tourner vers quelqu'un + d'autre. Apprenez à déchiffrer les journaux d'erreurs, et vous + vous apercevrez que la plupart des problèmes seront rapidement + identifiés . . . et résolus.

+ + +

Suexec

+ + +

Le programme suexec permet + d'exécuter les programmes CGI avec des droits différents selon le + serveur virtuel ou le répertoire utilisateur dans lequel ils + se situent. Suexec effectue une vérification des droits très + stricte, et toute anomalie détectée au cours de cette vérification + entraînera un echec d'exécution de votre programme CGI avec + affichage de l'erreur Premature end of script + headers.

+ +

Pour savoir si vous pouvez utiliser suexec, tapez la commande + apachectl -V, et regardez le chemin indiqué par + SUEXEC_BIN. Si au démarrage d'Apache, ce dernier + trouve un exécutable suexec dans ce chemin, + suexec sera activé.

+ +

Si vous ne maîtrisez pas le fonctionnement de suexec, il vous + est déconseillé de l'utiliser. Pour désactiver suexec, supprimer + simplement (ou renommez) l'exécutable suexec + pointé par SUEXEC_BIN et redémarrez le serveur. Si + après une lecture de suexec, vous + décidez quand-même de l'utiliser, tapez la commande suexec + -V pour voir où se situe le journal de suexec, et utilisez + ce dernier pour déterminer quelles règles vous violez + éventuellement.

+ +

Que se passe-t-il en coulisse

+ + +

Lorsque vos compétences en programmation CGI seront plus + poussées, il s'avérera intéressant pour vous de mieux comprendre ce + qui se passe en coulisse, et en particulier la manière dont le + navigateur et le serveur dialoguent entre eux. En effet, bien qu'il + soit tout à fait louable d'écrire un programme qui affiche "Bonjour + tout le monde . . .", cela ne sert pas à grand chose.

+ +

Variables d'environnement

+ + +

Les variables d'environnement sont des valeurs qui gravitent + autour de vous lorsque vous utilisez votre ordinateur. Elles sont + très utiles, à l'instar de votre chemin par défaut (où votre + ordinateur va rechercher le fichier physique correspondant à la + commande que vous avez tapée), votre nom d'utilisateur, le type de + votre terminal, etc... Pour obtenir une liste complète des + variables d'environnement standards que vous utilisez tous les + jours, tapez env dans votre interpréteur + de commandes.

+ +

Au cours de la transaction CGI, le serveur et le navigateur + définissent aussi des variables d'environnement, de façon à ce + qu'ils puissent communiquer entre eux. Ces variables définissent + entre autre le type de navigateur (Netscape, IE, Lynx), le type de + serveur (Apache, IIS, WebSite), le nom du programme CGI en cours + d'exécution, etc...

+ +

Ces variables sont à la disposition du programmeur CGI, et + elles constituent 50% de la communication client-serveur. La liste + complète des variables requises se trouve à + Common Gateway + Interface RFC.

+ +

Ce programme CGI basique en Perl permet d'afficher toutes les + variables d'environnement qui sont échangées. Deux programmes + similaires sont fournis avec la distribution d'Apache et situés + dans le répertoire cgi-bin. + Notez que certaines variables sont + obligatoires, alors que d'autres sont optionnelles, si bien que + vous verrez s'afficher certaines variables qui ne font pas partie + de la liste officielle. De plus, Apache vous propose de nombreuses + méthodes pour ajouter vos propres + variables d'environnement aux variables de base fournies par + défaut.

+ +

#!/usr/bin/perl
+use strict;
+use warnings;
+
+print "Content-type: text/html\n\n";
+foreach my $key (keys %ENV) {
+    print "$key --> $ENV{$key}<br>";
+}

+ + + +

STDIN et STDOUT

+ + +

L'entrée standard (STDIN) et la sortie standard + (STDOUT) constituent d'autres voies de communication + entre le client et le serveur. Dans un contexte normal, + STDIN correspond au clavier, ou à un fichier fourni + au programme à des fins de traitement, et STDOUT à la + console ou à l'écran.

+ +

Lorsque vous transmettez un formulaire web à un programme CGI + par la méthode POST, les données de ce formulaire + sont transcrites dans un format spécial et transmises à votre + programme CGI via STDIN. Le programme peut alors les + traiter comme si elles provenaient du clavier ou d'un + fichier.

+ +

Ce "format spécial" est très simple. Un nom de champ et sa + valeur sont reliés entre eux par un signe "égal" (=), et chacune + de ces paires nom champ/valeur est séparée de la suivante par un + "et" commercial (&). Les caractères + spéciaux comme les espaces, les "et" commerciaux, et les signes + "égal" sont convertis en leur équivalent hexadécimal pour éviter + qu'ils ne gâchent le travail. La chaîne contenant les données doit + ressembler à ceci :

+ +

+ name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey +

+ +

Vous verrez aussi parfois une chaîne de ce type accolée à une + URL. Dans ce cas, le serveur enregistre cette chaîne dans la + variable d'environnement appelée QUERY_STRING. On a + alors affaire à une requête de type GET. Votre + formulaire HTML indique laquelle des méthodes GET ou + POST est utilisée pour transmettre les données, en + définissant l'attribut METHOD au niveau de la balise + FORM.

+ +

Votre programme est ensuite chargé d'extraire les informations + utiles de cette chaîne. Heureusement, des bibliothèques et des + modules sont à votre disposition pour vous aider à traiter ces + données, et à gérer les différents aspects de votre programme + CGI.

+ +

Bibliothèques et modules CGI

+ + +

Pour écrire un programme CGI, il vous est conseillé d'utiliser + une bibliothèque de code, ou un module, qui effectueront une grande + partie du travail de base pour vous. Ceci vous permettra de diminuer + le nombre d'erreurs et d'accélérer le développement.

+ +

Si vous écrivez des programmes CGI en Perl, des modules sont à + votre disposition à CPAN. A ce + sujet, le module le plus populaire est CGI.pm. Vous + pouvez aussi essayer CGI::Lite, qui implémente les + fonctionnalités strictement nécessaires, mais suffisantes pour + la majorité des programmes.

+ +

Si vous écrivez des programmes CGI en C, vous disposez de nombreuses + options. L'une d'elles est la bibliothèque CGIC de https://web.mit.edu/wwwdev/www/cgic.html.

Pour plus d'informations

+ + +

La spécification CGI actuelle est disponible dans la Common Gateway + Interface RFC.

+ +

Lorsque vous postez une question à propos d'un problème CGI que + vous rencontrez, que ce soit dans une liste de diffusion ou dans un + newsgroup, faites en sorte de fournir suffisamment d'informations + sur le problème rencontré, ce que vous attendiez exactement, et en + quoi ce qui se produit est réellement différent de ce que vous + attendiez, quel serveur vous utilisez, en quel langage votre + programme CGI a été écrit, et, si possible, son code source. Ceci + permettra une résolution plus aisée de votre problème.

+ +

Notez que les questions à propos de problèmes CGI ne doivent + jamais être postées dans la base de données de + bogues d'Apache, à moins que vous ne soyez sûr d'avoir trouvé un + problème dans le code source d'Apache.