<-
Apache > Servidor HTTP > Documentaci�n > Versi�n 2.4 > How-To / Tutoriales

Tutorial de Apache: Contenido Din�mico con CGI

Idiomas disponibles:  en  |  es  |  fr  |  ja  |  ko 

Support Apache!

Consulte tambi�n

top

Introducci�n

CGI (Common Gateway Interface) es un m�todo por el cual un servidor web puede interactuar con programas externos de generaci�n de contenido, a ellos nos referimos com�nmente como programas CGI o scripts CGI. Es el m�todo m�s com�n y sencillo de mostrar contenido din�mico en su sitio web. Este documento es una introducci�n para configurar CGI en su servidor web Apache, y de iniciaci�n para escribir programas CGI.

top

Configurando Apache para permitir CGI

Para conseguir que sus programas CGI funcionen correctamente, deber� configurar Apache para que permita la ejecuci�n de CGI. Hay distintas formas de hacerlo.

Nota: Si Apache ha sido compilado con soporte de m�dulos compartidos, necesitar� que el m�dulo de CGI est� cargado; en su apache2.conf tiene que asegurarse de que la directiva LoadModule no ha sido comentada. Una directiva configurada correctamente ser�a as�:
LoadModule cgid_module modules/mod_cgid.so
En Windows, o si usa un mpm que no es multihilo, como prefork, una directiva configurada correctamente podr�a definirse as�:
LoadModule cgi_module modules/mod_cgi.so

ScriptAlias

La directiva ScriptAlias indica a Apache que un directorio se ha configurado espec�ficamente para programas CGI. Apache asumir� que cada fichero en este directorio es un programa CGI, e intentar� ejecutarlos cuando un cliente solicita este recurso.

La directiva ScriptAlias se puede definir as�:

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

El ejemplo que se muestra es de un archivo de configuraci�n apache2.conf por defecto si usted instal� Apache en la ubicaci�n por defecto. La directiva ScriptAlias es muy parecida a la directiva Alias, �sta define un prefijo de URL que se enlaza a un directorio en particular. Alias y ScriptAlias se usan generalmente para directorios que se encuentran fuera del directorio DocumentRoot. La diferencia entre Alias y ScriptAlias es que en ScriptAlias cualquier elemento debajo de ese prefijo de URL ser� considerado un programa CGI. As�, el ejemplo de m�s arriba le indica a Apache que cualquier solicitud para un recurso que comience con /cgi-bin/ deber�a servirse desde el directorio /usr/local/apache2/cgi-bin/, y deber�a tratarse como un programa CGI.

Por ejemplo, si se solicita la URL http://www.example.com/cgi-bin/test.pl, Apache intentar� ejecutar el archivo /usr/local/apache2/cgi-bin/test.pl y dar el resultado. Por supuesto el archivo debe existir y ser ejecutable, y dar el resultado de una manera espec�fica o Apache devolver� un mensaje de error.

CGI fuera de directorios ScriptAlias

Los programas CGI habitualmente se restringen a los directorios de ScriptAlias por razones de seguridad. De esta manera, los administradores pueden controlar de una manera m�s segura quien puede ejecutar programas CGI. Aun as�, si no se toman suficientes precauciones, no hay ninguna raz�n por la que programas CGI no se puedan ejecutar desde directorios seleccionados de manera arbitraria. Por ejemplo, quiz�s quiera permitir que usuarios del sistema tengan contenido web en sus directorios home con la directiva UserDir. Si quieren tener sus propios programas CGI, pero no tienen acceso al directorio principal cgi-bin, necesitar�n ser capaces de ejecutar sus scripts CGI en alg�n otro sitio.

Hay dos pasos a seguir para permitir la ejecuci�n CGI en directorios seleccionados de manera arbitraria. Primero, el handler cgi-script debe estar activado usando la directiva AddHandler o la directiva SetHandler. Segundo, el par�metro ExecCGI debe estar definido en la directiva Options.

Usando Options de manera expl�cita para permitir ejecuci�n de CGI

Puede usar la directiva Options, en el archivo de configuraci�n principal para especificar que se permite la ejecuci�n de CGI en un directorio en particular:

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

Esta directiva de aqu� arriba le indica a Apache que debe permitir la ejecuci�n de archivos CGI. Tambi�n necesitar� indicarle al servidor que los archivos son archivos CGI. La directiva AddHandler le indica al servidor que debe tratar a todos los archivos con la extensi�n cgi o pl como programas CGI:

AddHandler cgi-script .cgi .pl

Ficheros .htaccess

El tutorial .htaccess ense�a como activar programas CGI si no tienes acceso a apache2.conf.

Directorios de Usuario

Para permitir la ejecuci�n de programas CGI para cualquier archivo que acabe en .cgi en directorios de usuario, puedes usar la siguiente configuraci�n:

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

Si quiere designar un subdirectorio cgi-bin dentro de un directorio de usuario en el que todos los ficheros ser�n tratados como un programa CGI, puede usar lo siguiente:

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

Escribiendo un programa CGI

Hay dos diferencias principales entre programaci�n ``regular'' y programaci�n en CGI.

Primera, el resultado al completo de tu programa CGI debe estar precedido de una cabecera MIME-type. Esta cabecera HTTP le indica al cliente que tipo de contenido est� recibiendo. La mayor parte de las veces, �sto ser� algo como:

Content-type: text/html

Segunda, el resultado debe estar en formato HTML, o cualquier otro formato que su navegador sea capaz de mostrar. La mayor parte de las veces, ser� HTML, pero otras escribir� un programa CGI que devuelve una imagen gif, u otro contenido no-HTML.

Aparte de estas dos cosas, escribir un programa en CGI se parecer� bastante a cualquier otro programa que vaya a escribir.

Su primer programa CGI

A continuaci�n podr� ver un ejemplo de programa CGI que muestra una l�nea de texto en su navegador. Escriba lo siguiente, gu�rdelo en un archivo con el nombre first.pl, y p�ngalo en su directorio cgi-bin.

#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hola, Mundo.";

Incluso si Perl no le resulta familiar, podr� ver lo que est� ocurriendo aqu�. La primera l�nea le dice a Apache (o a cualquier shell en la que se est� ejecutando) que este programa puede ejecutarse con el int�rprete en la ubicaci�n /usr/bin/perl. La segunda l�nea imprime la declaraci�n de Content-Type que mencionamos antes, seguida de dos pares de retornos de carro. Esto pone una l�nea en blanco despu�s de la cabecera para indicar el final de las cabeceras HTTP, y el comienzo del cuerpo del contenido. La tercera imprime la cadena de caracteres "Hola, Mundo.". Y ese es el final del programa.

Si lo abre con su navegador favorito y le dice que solicite la direcci�n

http://www.example.com/cgi-bin/first.pl

o donde quiera que pusiera el archivo, ver� una l�nea Hola, Mundo. aparecer�n la ventana del navegador. No es muy emocionante, pero una vez que consiga que funcione podr� hacer lo mismo con casi cualquier programa.

top

�Pero todav�a no funciona!

Hay 4 cosas b�sicas que puede llegar a ver en su navegador cuando intenta acceder a un programa CGI desde la web:

El resultado del programa CGI
�Genial! Esto indica que todo funcion� correctamente. Si el resultado es correcto, pero el navegador no lo procesa correctamente, aseg�rese de que tiene especificado correctamente el Content-Type en su programa CGI.
El c�digo fuente de su programa CGI o un mensaje del tipo "POST Method Not Allowed".
Eso significa que no ha configurado Apache de manera apropiada para interpretar su programa CGI. Relea la secci�n de Configurando Apache e intente encontrar qu� le falta.
Un mensaje que empieza con "Forbidden"
Eso significa que hay un problema de permisos. Compruebe el Log de Errores de Apache y la secci�n de m�s abajo de Permisos de Fichero.
Un mensaje indicando "Internal Server Error"
Si comprueba el Log de errores de Apache, probablemente encontrar� que indica "Premature end of script headers", posiblemente acompa�ado de otro mensaje de error generado por su programa CGI. En este caso, querr� comprobar cada una de las secciones de m�s adelante para ver qu� impide que su programa CGI genere las cabeceras HTTP adecuadas.

Permisos de Fichero

Recuerde que el servidor no se ejecuta con su usuario. Es decir, cuando el servidor arranca, est� funcionando con un usuario sin privilegios, generalmente el usuario nobody, o www-data, as� que necesitar� permisos extra para ejecutar los archivos de los que usted es due�o. Generalmente, el m�todo para dar permisos suficientes para que se pueda ejecutar con nobody es dar permisos de ejecuci�n a todo el mundo en el fichero:

chmod a+x first.pl

Adem�s, si su programa lee desde o escribe a cualquier otro/s archivo/s, esos archivos necesitar�n tener los permisos correctos para permitir esas acciones.

Informaci�n de Ruta y Entorno

Cuando ejecuta un programa desde la l�nea de comandos, usted tiene cierta informaci�n que se le pasa a la shell sin que usted se percate de ello. Por ejemplo, usted tiene un PATH, que le indica a la shell d�nde debe buscar archivos a los que usted hace referencia.

Cuando un programa se ejecuta a trav�s del servidor web como un programa CGI, puede que no tenga el mismo PATH. Cualquier programa que invoque desde su programa CGI (como por ejemplo sendmail) necesitar� que se le indique la ruta absoluta, as� la shell puede encontrarlos cuando intenta ejecutar su programa CGI.

Una manifestaci�n com�n de esto es la ruta del int�rprete del script (a menudo perl) indicado en la primera l�nea de su programa CGI, que parecer� algo como:

#!/usr/bin/perl

Aseg�rese de que �ste es de hecho el path de su int�rprete.

Cuando edita scripts CGI en Windows, los caracteres de retorno de carro podr�an a�adirse a la l�nea donde se especifica el int�rprete. Aseg�rese de que los archivos se transfieren al servidor en modo ASCII. Fallar en esto puede acabar con avisos del tipo "Command not found" del Sistema Operativo, debido a que �ste no reconoce los caracteres de final de l�nea interpretados como parte del nombre de fichero del int�rprete.

Faltan Variables de Entorno

Si su programa CGI depende de variables de entorno no est�ndar, necesitar� asegurarse de que Apache pasa esas variables.

Cuando no encuentra ciertas cabeceras HTTP del entorno, aseg�rese de que est�n formateadas seg�n el RFC 2616, secci�n 4.2: Nombres de Cabeceras deben empezar con una letra, seguida solo de letras, n�meros o gui�n. Cualquier cabecera que no cumpla esta regla ser� ignorada de manera silenciosa.

Errores de Programa

La mayor parte de las veces cuando un programa CGI falla, es por un problema en el programa mismo. Esto ocurre generalmente cuando se maneja bien con "esto del CGI", y ya no comete los dos errores mencionados m�s arriba. Lo primero que hay que hacer es asegurarse de que su programa se ejecuta correctamente en l�nea de comandos antes de probarlo a trav�s del servidor web. Por ejemplo, intente:

cd /usr/local/apache2/cgi-bin
./first.pl

(No llame al int�rprete de perl. La consola y Apache tienen que poder encontrar el int�rprete usando l�nea l�nea de informaci�n en la primera l�nea del script.)

Lo primero que debe ver escrito por su programa es un conjunto de cabeceras HTTP, incluyendo el Content-Type, seguido de una l�nea en blanco. Si ve alguna otra cosa, Apache devolver� el error Premature end of script headers si intenta lanzar el script en el servidor web. Vea Escribiendo un programa CGI m�s arriba para m�s detalle.

Log de Errores

El log de errores es su amigo. Cualquier cosa que vaya mal generar� un mensaje en el log de errores. Deber�a mirar siempre ah� primero. Si el lugar donde est� alojando su sitio web no permite que acceda al log de errores, probablemente deber�a alojarlo en otro sitio. Aprenda a leer el log de errores y se dar� cuenta de que enseguida averiguar� el motivo del error y lo solucionar� r�pidamente.

Suexec

El programa de soporte suexec permite que programas CGI se ejecuten con permisos de usuario distintos, dependiendo del virtualhost o el directorio home donde se encuentren. Suexec tiene una comprobaci�n de permisos muy estricta, y cualquier fallo en esa comprobaci�n dar� como resultado un error con el mensaje Premature end of script headers.

Para comprobar si est� usando Suexec, ejecute apache2ctl -V y compruebe la ubicaci�n de SUEXEC_BIN. Si Apache encuentra un binario suexec al arrancar, suexec se activar�.

A menos que comprenda suxec perfectamente, no deber�a usarlo. Para desactivar suexec, basta con eliminar el binario suexec al que apunta SUEXEC_BIN y reiniciar el servidor. Si despu�s de leer sobre suexec todav�a quiere usarlo, entonces ejecute suexec -V para encontrar la ubicaci�n del fichero log de suexec, y use ese log para encontrar que pol�tica no est� cumpliendo.

top

�Qu� ocurre entre bastidores?

En cuanto tenga conocimiento avanzado de programaci�n CGI, le ser� �til comprender m�s de lo que ocurre entre bastidores. Espec�ficamente, c�mo el navegador y el servidor se comunican el uno con el otro. Porque aunque est� muy bien escribir un programa que diga "Hola, Mundo.", no tiene una gran utilidad.

Variables de Entorno

Las variables de entorno son valores que est�n ah� cuando usa el ordenador. Son cosas �tiles como el path (donde su ordenador busca el archivo espec�fico que se lanza cuando usted escribe un comando), su nombre de usuario, el tipo de terminal que usa, etc. Para una lista completa de la variables de entorno normales que se se usan en su d�a a d�a escriba env en la l�nea de comandos.

Durante la transacci�n CGI, el servidor y el navegador tambi�n configuran variables de entorno, y as� pueden comunicarse entre ellos. Cosas como el tipo de navegador (Netscape, IE, Lynx), el tipo de servidor (Apache, IIS, WebSite), el nombre del programa CGI que se est� ejecutando, etc.

Estas variables est�n disponibles para el programador de CGI, y son la mitad de la historia de la comunicaci�n cliente-servidor. La lista completa de las variables necesarias se encuentra en el RFC de Common Gateway Interface.

Este sencillo programa CGI en Perl mostrar� todas las variables de entorno que se est�n pasando entre el cliente y el navegador. Dos programas similares est�n incluidos en el directorio cgi-bin de la distribuci�n de Apache. Tenga en cuenta que algunas variables son necesarias mientras que otras son opcionales, as� que es posible que vea algunas variables que no est�n en la lista oficial. Adicionalmente, Apache aporta distintas maneras diferentes para que pueda a�adir sus variables de entorno a las b�sicas que se proveen por defecto.

#!/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 y STDOUT

Otra comunicaci�n entre el servidor y el cliente ocurre en la entrada est�ndar (STDIN) y la salida est�ndar (STDOUT). En el contexto normal de cada d�a, STDIN es la entrada con el teclado, o un fichero que se le da a un programa para que act�e sobre �l, y STDOUT generalmente es la consola o la pantalla.

Cuando hace POST con un formulario de web a un programa CGI, los datos en ese formulario se empaquetan en un formato especial que se entrega a su programa CGI en el STDIN. Entonces el programa puede procesar la informaci�n como si le llegara desde el teclado, o desde un fichero.

El "formato especial" es muy sencillo. Un nombre de campo y su valor se asocian juntos con el signo igual (=), y pares de valores se asocian juntos con el ampersand � et en espa�ol (&). Caracteres inconvenientes como los espacios, ampersands y signos de igual, se convierten en su equivalente hexadecimal para no impidan el funcionamiento correcto del programa. La cadena de datos al completo ser� algo como:

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

A veces tendr� este tipo de cadena de caracteres al final de una URL. Cuando esto ocurre, el servidor pone esa cadena en una variable de entorno que se llama QUERY_STRING. Esto se llama solicitud GET. Su formulario HTML especifica si se usa un GET o un POST para entregar la informaci�n, configurando el atributo METHOD en la etiqueta FORM.

Su programa es el responsable de convertir esa cadena de caracteres en informaci�n �til. Afortunadamente, hay librer�as y m�dulos disponibles que ayudan a procesar la informaci�n, as� como a gestionar los distintos aspectos de su programa CGI.

top

M�dulos/librer�as CGI

Cuando escribe programas CGI, deber�a considerar usar una librer�a de c�digo, o m�dulo, para hacer todo el trabajo m�s arduo por usted. Esto lleva a tener menos errores y un desarrollo de c�digo m�s r�pido.

Si est� escribiendo un programa CGI en Perl, existen m�dulos disponibles en CPAN. El m�dulo m�s conocido para este prop�sito es CGI.pm. Quiz�s quiera considerar CGI::Lite, que implementa una funcionalidad m�nima, que es todo lo que se necesita en la mayor�a de los programas.

Si est� escribiendo programas CGI en C, hay varidad de opciones. Una de estas es la librer�a CGIC, de http://www.boutell.com/cgic/.

top

Para m�s informaci�n

La especificaci�n actual de CGI est� disponible en el RFC de Common Gateway Interface.

Cuando env�e una pregunta sobre un problema de CGI, o bien a una lista de correo, o a un grupo de noticias, aseg�rese de que facilita suficiente informaci�n de lo que ha ocurrido, de lo que espera que ocurra, y de lo que est� ocurriendo en su lugar que es diferente, el servidor que est� ejecutando, en qu� lenguaje CGI est� hecho su programa, y si es posible, el c�digo que falla. Esto har� encontrar el problema mucho m�s f�cil.

Tenga en cuenta que las preguntas sobre problemas CGI nunca deber�an enviarse a la base de datos de bugs de bugs de Apache a menos que est� seguro de haber encontrado un problema en el c�digo fuente de Apache.

Idiomas disponibles:  en  |  es  |  fr  |  ja  |  ko 

top

Comentarios

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.