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

Tutorial do Apache: arquivos .htaccess

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.

Support Apache!

Veja também

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