<-
Apache > Servidor HTTP > Documenta��o > Vers�o 2.4 > How-To / Tutoriais

Tutorial do Apache: arquivos .htaccess

L�nguas Dispon�veis:  en  |  fr  |  ja  |  ko  |  pt-br 

Esta tradu��o pode estar desatualizada. Confira a vers�o em Ingl�s para mudan�as recentes.

Arquivos .htaccess oferecem um meio de fazer mudan�as nas configura��es por-diret�rio.

top

Arquivos .htaccess

top

O que eles s�o/Como us�-los

Os arquivos .htaccess (ou "arquivos de configura��o distribu�da") oferecem um meio de fazer mudan�as nas configura��es por-diret�rio. Um arquivo, contendo uma ou mais diretrizes de configura��es, � colocado em um diret�rio em particular, e as diretrizes se aplicam para aquele diret�rio e todos os seu subdiret�rios subseq�entes.

Nota:

Se voc� quiser renomear o seu arquivo .htaccess para outro nome, voc� deve usar a diretriz AccessFileName. Por exemplo, se voc� prefere que o arquivo se chame .config, ent�o voc� pode adicionar a seguinte linha ao seu arquivo de configura��o do servidor:

AccessFileName .config

No geral, arquivos .htaccess usam a mesma sintaxe que os arquivos de configura��o principal. O que voc� pode colocar nesses arquivos � determinado pele diretriz AllowOverride. Essa diretriz especifica, em categorias, quais diretrizes ser�o aceitas caso sejam encontradas em um arquivo .htaccess. Se uma diretriz for permitida em um arquivo .htaccess, a documenta��o para essa diretriz ir� conter uma se��o Override, especificando que valor precisa estar em AllowOverride para que esta diretriz seja permitida.

Por exemplo, se voc� procurar na documenta��o pela diretriz AddDefaultCharset, voc� achar� que ela � permitida nos arquivos .htaccess. (Veja a linha Contexto no sum�rio das diretivas.) A linha Override l� FileInfo. Ent�o, voc� deve ao menos ter AllowOverride FileInfo para que essa diretriz seja aceita nos arquivos .htaccess.

Exemplo:

Contexto: configura��o do servidor, hospedeiros virtuais, diret�rio, .htaccess
Override: FileInfo

Se voc� estiver incerto se uma diretriz em particular � aceita em um arquivo .htaccess, procure na documenta��o por essa diretriz, e verifique a linha de Contexto por ".htaccess".

top

Quando (n�o) usar arquivos .htaccess

No geral, voc� nunca deve usar arquivos .htaccess a n�o ser que voc� n�o tenha acesso ao arquivo de configura��o principal do servidor. Existe, por exemplo, um erro de concep��o que dita que a autentica��o de usu�rios sempre deve ser feita usando os arquivos .htaccess. Esse simplesmente n�o � o caso. Voc� pode usar as configura��es de autentica��o de usu�rio no arquivo de configura��o principal do servidor, e isso �, de fato, a maneira mais adequada de se fazer as coisas.

Arquivos .htaccess devem ser usados em casos onde os provedores de conte�do do site precisem fazer mudan�as na configura��o do servidor por-diret�rio, mas n�o tem acesso root ao sistema do servidor. Caso o administrador do servidor n�o esteja disposto a fazer mudan�as freq�entes nas configura��es do servidor, � desej�vel permitir que os usu�rios possam fazer essas mudan�as atrav�s de arquivos .htaccess eles mesmos. Isso � particularmente verdade, por exemplo, em casos onde provedores est�o fornecendo m�ltiplos sites para usu�rios em apenas uma m�quina, e querem que seus usu�rios possam alterar suas configura��es.

No entanto, de modo geral, o uso de arquivos .htaccess deve ser evitado quando poss�vel. Quaisquer configura��es que voc� considerar acrescentar em um arquivo .htaccess, podem ser efetivamente colocadas em uma se��o <Directory> no arquivo principal de configura��o de seu servidor.

Existem duas raz�es principais para evitar o uso de arquivos .htaccess.

A primeira delas � a performance. Quando AllowOverride � configurado para permitir o uso de arquivos .htaccess, o Apache procura em todos diret�rios por arquivos .htaccess. Logo, permitir arquivos .htaccess causa um impacto na performance, mesmo sem voc� us�-los de fato! Al�m disso, o arquivo .htaccess � carregado toda vez que um documento � requerido.

Al�m disso, note que o Apache precisa procurar pelos arquivos .htaccess em todos os diret�rios superiores, para ter o complemento total de todas as diretivas que devem ser aplicadas. (Veja a se��o como as diretrizes s�o aplicadas.) Ent�o, se um arquivo de um diret�rio /www/htdocs/example � requerido, o Apache precisa procurar pelos seguintes arquivos:

/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess

Assim, para cada acesso de arquivo fora desse diret�rio, existem 4 acessos ao sistema de arquivos adicionais, mesmo que nenhum desses arquivos estejam presentes. (Note que esse s� ser� o caso se os arquivos .htaccess estiverem habilitados para /, o que normalmente n�o � o verdade.)

A segunda considera��o � relativa � seguran�a. Voc� est� permitindo que os usu�rios modifiquem as configura��es do servidor, o que pode resultar em mudan�as que podem fugir ao seu controle. Considere com cuidado se voc� quer ou n�o dar aos seus usu�rios esses privil�gios. Note tamb�m que dar aos usu�rios menos privil�gios que eles precisam, acarreta em pedidos de suporte t�cnico adicionais. Tenha certeza que voc� comunicou aos usu�rios que n�vel de privil�gios voc� os deu. Especificar exatamente o que voc� configurou na diretriz AllowOverride, e direcion�-los para a documenta��o relevante, ir� poup�-lo de muita confus�o depois.

Perceba que � exatamente equivalente colocar o arquivo .htaccess em um diret�rio /www/htdocs/example contendo uma diretriz, e adicionar a mesma diretriz em uma se��o Directory <Directory /www/htdocs/example> na configura��o principal do seu servidor:

Arquivo .htaccess em /www/htdocs/example:

Conte�do de um arquivo .htaccess em /www/htdocs/example

AddType text/example .exm

Se��o do seu arquivo apache2.conf

<Directory /www/htdocs/example>
AddType text/example .exm
</Directory>

No entanto, adicionando isso ao seu arquivo de configura��o do servidor resultar� em uma menor perda de performance, na medida que a configura��o � carregada no momento da inicializa��o do servidor, ao inv�s de toda que que um arquivo � requerido.

O uso de arquivos .htaccess pode ser totalmente desabilitado, ajustando a diretriz AllowOverride para none:

AllowOverride None

top

Como as diretrizes s�o aplicadas

As diretrizes de configura��o que se encontram em um arquivo .htaccess s�o aplicadas para o diret�rio no qual o arquivo .htaccess se encontra, e para todos os subdiret�rios ali presentes. Mas, � importante lembrar tamb�m que podem existir arquivos .htaccess no diret�rios superiores. As diretrizes s�o aplicadas na ordem que s�o achadas. Logo, um arquivo .htaccess em um diret�rio em particular, pode sobrescrever as diretrizes encontradas em um diret�rio acima deste em sua respectiva �rvore. Estes, por sua vez, podem ter suas diretrizes sobrescritas por diretrizes ainda mais acima, ou no pr�prio arquivo de configura��o principal do servidor.

Exemplo:

No diret�rio /www/htdocs/example1 n�s temos um arquivo .htaccess contendo o seguinte:

Options +ExecCGI

(Nota: voc� deve ter "AllowOverride Options" para permitir o uso da diretriz "Options" nos arquivos .htaccess .)

No diret�rio /www/htdocs/example1/example2 n�s temos um arquivo .htaccess contendo:

Options Includes

Devido a esse segundo arquivo .htaccess, no diret�rio /www/htdocs/example1/example2, a execu��o de scripts CGI n�o � permitida, pois somente Options Includes est� em efeito, o que sobrescreve completamente quaisquer outros ajustes previamente configurados.

top

Exemplo de Autentica��o

Se voc� veio diretamente � esta parte do documento para aprender como fazer autentica��o, � importante notar uma coisa. Existe uma concep��o errada, mas muito comum, de que � necess�rio o uso de arquivos .htaccess para implementar a autentica��o por senha. Este n�o � o caso. Colocar diretrizes de senha em uma se��o <Directory>, no seu arquivo principal de configura��o do servidor, � a melhor maneira de se implementar isto, e os arquivos .htaccess devem ser usados apenas se voc� n�o tem acesso ao arquivo principal de configura��o do servidor. Veja acima a discuss�o sobre quando voc� deve e quando n�o deve usar os arquivos .htaccess.

Dito isso, se voc� ainda acredita que precisa usar um arquivo .htaccess, a configura��o a seguir provavelmente funcionar� para voc�.

Conte�do de um arquivo .htaccess:

AuthType Basic
AuthName "Password Required"
AuthUserFile /www/passwords/password.file
AuthGroupFile /www/passwords/group.file
Require Group admins

Note que AllowOverride AuthConfig precisa estar habilitado para que estas diretrizes tenham efeito.

Por favor veja o tutorial de autentica��o para uma discuss�o mais completa sobre autentica��o e autoriza��o.

top

Exemplo de Server Side Includes

Outro uso comum de arquivos .htaccess � ativar o Server Side Includes para um diret�rio em particular. Isto pode ser feito com as seguintes diretrizes de configura��o, colocadas em um arquivo .htaccess no diret�rio desejado:

Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml

Note que ambos AllowOverride Options e AllowOverride FileInfo precisam estar habilitados para essas diretrizes terem efeito.

Por favor veja o tutorial de SSI para uma discuss�o mais completa sobre server-side includes.

top

Exemplo de CGI

Finalmente, voc� pode querer que um arquivo .htaccess permita a execu��o de programas CGI em um diret�rio em particular. Isto pode ser implementado com as seguintes configura��es:

Options +ExecCGI
AddHandler cgi-script cgi pl

Alternativamente, se voc� desejar que todos os arquivos de um dado diret�rio, sejam considerados programas CGI, isso pode ser feito com a seguinte configura��o:

Options +ExecCGI
SetHandler cgi-script

Note que ambos AllowOverride Options e AllowOverride FileInfo precisam estar habilitados para que essas diretrizes tenham quaisquer efeito.

Por favor veja o tutorial de CGI tutorial para uma discuss�o mais completa sobre programa��o e configura��o CGI.

top

Resolvendo Problemas

Quando voc� adiciona diretrizes de configura��o em um arquivo .htaccess, e n�o obt�m o efeito desejado, existe uma s�rie de pontos que podem estar errados.

Mais comumente, o problema � que a diretriz AllowOverride n�o est� habilitada corretamente para que as suas diretrizes de configura��es sejam honradas. Verifique se voc� n�o possui AllowOverride None ajustado para o escopo do arquivo em quest�o. Um bom meio de testar isso � colocar "lixo" em seu arquivo .htaccess e recarreg�-lo. Se n�o for gerado nenhum erro do servidor, certamente voc� tem AllowOverride None habilitado.

Se, por outro lado, voc� est� obtendo erros do servidor ao tentar acessar documentos, verifique o registro de erros do Apache. Ele provavelmente ir� indicar que a diretriz usada em seu arquivo .htaccess n�o � permitida. Alternativamente, ele pode acusar erros de sintaxe que voc� ter� que corrigir.

L�nguas Dispon�veis:  en  |  fr  |  ja  |  ko  |  pt-br 

top

Coment�rios

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.