DicionariodaInternet: CGI

CGI (Common Gateway Interface) - método utilizado na execução de programas (scripts) para a interação com textos ou outros dados no [servidor] [Web], geralmente usam a linguagem [PERL] e ficam instalados no [servidor] dentro de uma pasta chamada cgi-bin.

4.1) Visão Geral

4.1.1) O que são scripts cgi?

"cgi" significa "common gateway interface", um nome interessante que significa programas de computador rodando em um servidor web e que podem ser invocados apartir de um página WWW através do browser. A parte "bin" se refere aos executáveis binários que resultam da compilação dos programas.

O típico uso de cgi é no processamento de formulários online. Quando o usuário preenche os campos de um formulário e pressiona o botão de submit, o programa cgi especificado no html será executado no servidor e a informação preenchida no formulário será disponibilizada ao programa como parametros. O programa, sendo um programa, poderá fazer qualquer coisa que o programador deseje fazer.

"cgiemail", por exemplo, é um programa escrito em C que se apropria do conteúdo dos campos de um formulário e em seguida o envia por email a um destinatário específico, que então gera uma página WWW confirmando a ação.

4.1.2) Onde eu devo colocar os scripts cgi-bin?

Ponha seus scripts cgi-bin no seu subdiretório chamado cgi-bin.

Se o seu domínio é do tipo seunome.com, você então poderá acessar seus scritps em /cgi-bin/

4.1.3) Qual o path de date, mail, perl ...?

Para encontrar o path do programa data digite wich date. Faça o mesmo para qualquer programa que você precise que seu script cgi-bin acesse.

Estes são os mais comuns:

    * Sendmail: /usr/sbin/sendmail
    * Perl5.003: /usr/bin/perl
    * Perl5.004: /usr/bin/perl5.004 (não há suportepara Full 5.004 lib atualmente)
    * Date: /bin/date
    * Java:/usr/bin/java
    * Python:/usr/bin/python

Eu ví vários tipos de perls, qual deles deverei usar?

Eles devem ser todos os mesmos. /usr/bin/perl deverá funcionar bem.

4.2)FORMULÁRIOS DE RESPOSTA E SIMILARES

Para formulários simples e na maioria das vezes prefira formmail (cgiemail que é mais trabalhoso de entender e configurar).

Nós provemos formmail através do painel de controle. Desta forma, será chamado através de um URL como /cgi-sys/FormMail?.cgi os detalhes são fornecidos abaixo.

Formmail Formmail.cgi

Formmail é um programa escrito na linguagem Perl que se apropria do conteúdo de caixas em um formulário e os envia por email para um destino específico. Em adição ele é capaz de gerar sua própria página de confirmação.

Campos de Formulários Necessários:

Existe apenas um campo do formulário que TEM que estar nele para funcionar corretamente:o campo recipient.

Campo: recipient

Descrição: Este campo de formulário permite configurar para quem desejamos que seja enviado o resultado do formulário. A maioria deverá preferir configurar esta opção como um campo hidden com um valor igual ao seu email.

Sintaxe:

Campos Opcionais:

Campo: subject

Descrição: O campo subject permitirá que especifique o subject que irá aparecer no email enviado com o resultado do formulário. Se você não tiver esta opção como on, então o script enviará a mensagem default: WWW Form Submission

Sintaxe:

Se você deseja escolher o subject: <input type=hidden name="subject" value="Your Subject">

Para permitir ao usuário escolher o subject: <input type=text name="subject">

Campo: email

Descrição: O campo email permite ao usuário especificar seu endereço de email. SE você deseja retornar emails ao usuário, então é recomendável que inclua este campo ao seu formulário.

Sintaxe:

Campo: realname

Descrição: O campo realname do formulário permitirá que o usuário inclua seu nome real.

Sintaxe:

Campo: redirect

Descrição: Se você desejar redirecionar o usuário para um novo URL ao invés da página default de resposta, você poderá usar esta variável hidden para enviá-lo a uma página HTML pré-formatada.

Sintaxe:

Para permitir que o usuário escolha o destino que deseja ir após completer o formulário:<input type=text name="redirect">

Campo: required

Version Added: 1.3

Descrição: Você poderá requerer que o usuário obrigatóriamente preencha alguns campos antes que possa submeter o formulário. Apenas coloque todos os nomes de campo nesta opção. Caso os campos requeridos não sejam preenchidos o usuário será notificado sobre o que ele necessita preencher e um link de volta ao formulário aparecerá.

Sintaxe:

Caso você deseje requerer que os campos email e phone no seu formulário, use a sintaxe: <input type=hidden name="required" value="email,phone"> Campo: env_report

Version Added: 1.3

Descrição: Permite que você tenha algumas informações extras incluidas no email que você recebe do usuário após o preenchimento do seu formulário. Util para saber qual o browser utilizado, de que domínio ele vem e outros atributos. A seguir uma pequena lista de algumas destas variáveis uteis:

REMOTE_HOST - envia o hostname de origem do cliente. REMOTE_ADDR - envia o endereço IP de origem do cliente. REMOTE_USER - Se o servidor suportar autenticação e o script é protegido, este será o username que ele terá autenticado.

Isto não é normalmente setado on.*

REMOTE_IDENT - Se o servidor suportar identificação RFC 931, então Esta variavel irá ser setada para o username remoto recebido do servidor. *Isto não é normalmente setado on.* HTTP_USER_AGENT - O browser que o usuário está usando para mandar o formulário. Formato: software/version library/version

Existem outras variáveis, mas estas são algumas das mais úteis.

Sintaxe:

Se desejar descobrir qual o host remote e o browser do cliente ponha o seguinte no seu formulário: <input type=hidden name="env_report" value="REMOTE_HOST,HTTP_USER_AGENT">

Campo: sort

Version Added: 1.4

Descrição: Este campo permite que você escolha a ordem que as respostas enviadas através do email apareçam. Você pode escolher em ter os campos ordenados alfabeticamente ou específicamente estabelecer a ordem que deseja. Deixando este campo prá lá, a ordem simplesmente será aquela enviada por default pelo browser (que nem sempre é a mesma ordem que aparece no formulário.) Quando ordenar uma serie de campos use a frase "order:" como a primeira parte do valor do campo sort, e então complete com os campos que você deseja que apareçam listados separados por virgulas.

Sintaxe:

Ordenar alfabeticamente: <input type=hidden name="sort" value="alphabetic">

Para ordenar uma série de campos: <input type=hidden name="sort" value="order:name1,name2,etc...">

Campo: print_config

Version Added: 1.5

Descrição: print_config permite que se escolha quais das variaveis de config desejamos que sejam impressas no email. Por default, nenhum campo de config é impresso em seu email, porque todos os campos importantes email, subject, etc... estão incluídos na mensagem.

Sintaxe:

Caso você queira imprimir os campos email e subject no corpo do seu email inclua o tag: <input type=hidden name="print_config" value="email,subject">

Campo: title

Version Added: 1.3

Descrição: Este campo do formulário permite que você especifique o título e cabeçalho da página de resultado caso você não tenha especificado o redicionamente para outro URL

Sintaxe:

Se você quer um título 'Resultado do Formulário': <input type=hidden name="title" value="Resultado do Formulário">

Campo: return_link_url

Version Added: 1.3

Descrição: Este campo do formulário permite que você especifique o URL que irá aparecer como, return_link_title, na pagina de resultado. Este campo não será usado quando utilizarmos o campo redirect, será útil caso queira permitir ao usuário receber o resultado naquela página mas permitir a ele uma maneira de voltar a sua página principal.

Sintaxe:

Campo: return_link_title

Version Added: 1.3

Descrição: Este campo do formulário permite que você especifique o titulo da URL que irá aparecer como, return_link_title, na pagina de resultado Os dois campos serão apresentados na página de resultados como:

    * <a href="return_link_url">return_link_title

Sintaxe:

<input type=hidden name="return_link_title" value="Back to Main Page"> Campo: background

Version Added: 1.3

Descrição: Este campo do formulário permite especificar o fundo da página de resultados, caso você não opte pelo redirect. Esta imagem aparecerá como background da página de resultados.

Sintaxe:

<input type=hidden name="background" value=http://seudominio.com.br/images/image.gif>; Campo: bgcolor

Version Added: 1.3

Descrição: Este campo do formulário permite especificar a cor de fundo da página de resultados, caso você não opte pelo redirect. Esta imagem aparecerá como background da página de resultados.

Sintaxe:

Para um fundo de página branco: <input type=hidden name="bgcolor" value="#FFFFFF">

Campo: text_color

Version Added: 1.3

Descrição: Este campo atua da mesma forma que bgcolor, exceto que este irá mudar a cor do seu texto.

Sintaxe:

Para os textos em preto: <input type=hidden name="text_color" value="#000000">

Campo: link_color

Version Added: 1.3

Descrição: Muda as cores dos links na página de resultados. Trabalha da mesma forma que text_color. Não deverá ser definida caso use redirect.

Sintaxe:

Para um link em vermelho: <input type=hidden name="link_color" value="#FF0000">

Campo: vlink_color

Version Added: 1.3

Descrição: Muda as cores dos links visitados na página de resultados. Trabalha da mesma forma que text_color. Não deverá ser definida caso use redirect.

Sintaxe:

Para um link visitado azul: <input type=hidden name="vlink_color" value="#0000FF">

Campo: alink_color

Version Added: 1.4

Descrição: Muda as cores dos links visitados na página de resultados. Trabalha da mesma forma que text_color. Não deverá ser definida caso use redirect.

Sintaxe:

Para um link visitado azul: <input type=hidden name="alink_color" value="#0000FF">

Para um exemplo de um formulário completo clique aqui e consulte o código da página

CGIEMAIL Visite inicialmente nosso faq para uma explicação rápida sobre o funcionamento do CGI-EMAIL.

Cgiemail é um programa escrito em linguagem C que se apropria do conteúdo das caixas de dialogo de um formulário e o envia por email para um destino específico. Adicionalmente as especificações do formulário no arquivo .html, uma especificação em um arquivo .txt é necessária para formatar o resultado para uma mensagem de email.

Nós provemos cgiemail no diretório CGI-BIN de cada máquina. Desta forma, será chamado através de um URL como /cgi-bin/cgiemail/mail.txt. Detalhes são fornecidos abaixo.

Apesar de existirem diversas sub-sessões abaixo, todas trabalham juntas oque significa que esta parte deverá ser lida do início até o seu final.

4.2.1)add.html

Se você nunca lidou antes com formulários não se apavore. Eles são fáceis de serem criados e entendidos.Os exemplos fáceis estão a seguir. Você não precisará de seguir todos os exemplos para compreender corretamente o que será apresentado a seguir.

Cada tag de <input> especifica um record. Esta chave é dada pelo atributo name, e o valor pelo atributo value. O atributo type diz ao the browser que tipo de dados esperar. Agora, tentemos olhando o exemplo.

Por favor note que os itens hidden (ocultos) são utilizados para passar informações críticas ao cgiemail. Elas dizem a localização do arquivo sucesso, o nome da pessoa que o enviou e o subject do formulário. Quando construir seus próprios formulários, você (definitivamente) deverá mudar o endereço de email no campo "required-to", e o subject no campo "subject" . O primeiro item diz ao cgiemail oque mostrar quando o formulário for preenchido com sucesso pelo usuário.

Após isso vem os campos que são paresentados ao usuário. Você poderá preferir utilizar campos input type=text com; é uma forma fácil e simples. O tamanho size=60 diz ao browser qual o tamanho da caixa. O name=something é required em cada tag de input, de outra forma o browser não saberá com enviar estes dados ao servidor. O atributo value="" é correto na maioria dos casos, ao menos que deseje um valor default no formulário.

Note que se o campo inciar com required-, cgiemail irá requerer que o usuário entre com um valor neste campo. Isso é particularmente útil quando desejamos que o usuário entre com seu email, por exemplo.

Quando o usuario pressiona o botão Submit, os dados são enviados para sua máquina onde cgiemail começa a fazer alguma coisa com eles. O que ele faz é controlado por ...

4.2.2) Mail.txt

Tenha certeza de dar seu upload no modo ASCII.

Falhas em upload mail.txt em modo ASCII irá gerar a seguinte mensagem:

Server Error The server encountered an internal error or misconfiguration and was unable to complete your request.

Agora que temos todos os dados oque faremos com eles? Envia-los por email, é claro! Mas pela sua flexibilidade, cgiemail requer que você crie um arquivo mail.txt para mostrar-lhe o que está sendo enviado. (Se você não necessita desta flexibilidade use um link mailto.) O programa lerá neste arquivo, fará as substituições, e as passará ao sistema de email.

Primeiro, como cgiemail sabe onde encontrar este arquivo? Olhe na primeira linha em formulário de exemplo utilizado na parte anterior. Um pouco depois da palavra cgiemail no atributo action diz ao cgiemail como se parecer. Quando chamamos de SEUNOME, cgiemail não sabe qual é o seu domínio porque está instalado para todos. Assim, o primeiro componente deste path deverá ser seunome. Depois disso, ele vai para o seu diretório WWW o aparece lá. Se você tem um domínio, nós sugerimos que você, explicitamente, coloque o atributo action, porque a situação muda: cgiemail sabe quem é o seu domínio quando chamado dele.

Seunome.com poderá querer por seu arquivo mail.txt no seu diretório www. Seu formulário então iniciará com

<form method=post action=http://www.seunome.com.br/cgi-bin/cgiemail/mail.txt>;

Dequalquer maneira, não há nada de mágico no nome mail.txt. Fique livre para chamá-lo como mail1.txt, ou form1.mail, ou qualquer coisa que desejar, enquanto o formulário tiver o nome correto para aquele que você deu upload.

Aqui está o mail.txt que nós usamos com o formulário apresentado anteriormente. É muito simples. Note que as primeiras linhas são cabeçalhos de email. Você provavelmente não necessitará mudar esta parte ou as partes correspondentes do seu formulário. Em particular, tem que haver um header To: ou o email não irá para lugar nenhum!

O que cgiemail faz é apenas substituir todas as strings que parecem com [key] com o valor que o usuario digitou no campo com name=key. Só isso.

Você também poderá acrescentar enxertos de textos para ajudar a formatar a saída. Apenas as partes [key] são substituídas por cgiemail.

4.2.3) Como usar cgiemail

Se você já leu as duas últimas partes você já deverá saber o bastante prá usar cgiemail. Assim vamos a um pequeno sumário:

   1. Tenha o seu formulário e o arquivo mail.txt. Se preferir pode editar online e depois dar um upload pro seu diretório www.
   2. Substitua 'thelist' no formulário com seu domínio.
   3. Edite o formulário para ter as áreas de input de sua preferencia.
   4. Edite o arquivo mail.txt para casar com os inputs.
   5. Tenha suas variáveis começando com o name required- se você deseja obrigar o usuário a entrar com estes campos. (Como o 'required-to' no exemplo.) Lembre-se de mudar tanto no formulário (.html) com no template (mail.txt).
   6. Você poderá alterar a variável de sucesso no formulário HTML para personalizar a mensagem que o cliente recebe após preencher o formulário.
   7. Espere! O que nós lhe demos foi apenas um exemplo de formulário, e não um formulário completo. Coloque as coisas necessárias para transformá-lo nisso. (Ao menos entre um par de <body> </body> )
   8. Caso os tenha editado off-line, dê um upload nos arquivos.
   9. Tente e brinque com ele.

4.6) Problemas (Esta sessão irá crescer na medida em que nós nos lembrarmos de adicionar os problemas com os quais nos deparamos no dia-dia.)

"Quando eu ativo meu programa CGI, eu recebo uma mensagem que diz 'Server Misconfigured'".

Dê um Telnet e vá até o seu diretório httpd/cgi-bin. Tente rodar o programa localmente (perl -w nomedoscript.cgi) para ver quais erros obtem. Lembre-se que quando um CGI produz um erro, a saída é descartada e o que você obtém é uma pagina genérica de erro. Para checar tudo você terá de rodar o programa você mesmo.

Você pode ver o arquivo de erros (error_log) em httpd/logs.

Se você obter algo como

bash: ./search.pl: No such file or directory

e você tem certeza de haver digitado o nome corretamente, é quase certo que você deu o upload do progama no modo binário. Scrits Perl são texto ASCII e devem seur subidos no modo ASCII. (Da mesma forma que shell scripts e quaisquer outros tipos de script que começem com '#!' na primeira linha.) Você saberá que é isso se ./search.pl não funcionar e perl search.pl sim. Assumindo que você não tem nenhuma carriage return no programa (duvidável), isso vai consertar:

    mv search.pl search.pl.txt && tr -d '\r' search.pl

Aí temos a resposta:

Literal @seunome now requires backslash at ./bigones line 16, within string

Muitos dos scripts que você vai encontrar em distribuição por aí são ainda escritos para Perl versão 4. Nosso /usr/bin/perl é versão 5, que é 99.9% compativel com a versão, com muitos melhoramentos. Você então encontrou o outro 0.1%.

Em Perl 4, você pode escrever um argumento como

$mailaddress = "joe@schmoe.com";

porque Perl não sabe que o signo '@' é uma string especial. Perl 5 sabe, assim você deverá escapa-la assim:

$mailaddres = "joe\@schmoe.com";

Você não pode sair mudando todos os '@' por '\@', apenas aqueles em strings. Para agilizar seu serviço Perl lhe diz o número da linha problematica através da sua mensagem de erro. (Para checá-lo sem acidentalmente rodar o programa, use perl -c script.) Conserte-o e veja se funciona.

Tom Christianson (muito conhecido no mundo Perl) escreveu The Idiot's Guide to Solving Perl CGI problems (o guia dos idiotas para resolver problemas com perl) para o newsgroup comp.lang.perl.misc. Nem tudo é correto para o setup de http://seudominio.com.br mas será bem útil.