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 :

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 :

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 :

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 :

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 :

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.

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

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

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 :

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 :

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 :

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

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.

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 :

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.