Tutorial de Apache: Contenido Dinámico con CGI

+

Introducción

Módulos Relacionados	Directivas Relacionadas
`mod_alias` `mod_cgi` `mod_cgid`	`AddHandler` `Options` `ScriptAlias`

+ + + +

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.

+

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 httpd.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 + httpd.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 + httpd.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>

+ + +

+

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.

+ +

+

¡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 + apachectl -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.

+ +

+

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

+ +

+

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/. +

+

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.

+

Consulte también

Introducción

Configurando Apache para permitir CGI

ScriptAlias

CGI fuera de directorios ScriptAlias

Usando Options de manera explícita para permitir ejecución de + CGI

Ficheros .htaccess

Directorios de Usuario

Escribiendo un programa CGI

Su primer programa CGI

¡Pero todavía no funciona!

Permisos de Fichero

Información de Ruta y Entorno

Faltan Variables de Entorno

Errores de Programa

Log de Errores

Suexec

¿Qué ocurre entre bastidores?

Variables de Entorno

STDIN y STDOUT

Módulos/librerías CGI

Para más información

Comentarios