Diretivas essenciais do Apache para iniciantes: ServerName, DocumentRoot, DirectoryIndex e Options

O que são diretivas “essenciais” e por que elas causam problemas

Diretivas são linhas de configuração que controlam como o Apache atende requisições. As mais usadas em cenários reais (e que mais geram confusão) são as que definem identidade do site, pasta publicada, arquivo inicial, permissões e comportamento de diretórios. Pequenos erros nelas podem causar: site fora do ar, conteúdo errado sendo servido, exposição de arquivos por listagem de diretório, ou permissões negadas (403).

Como editar com segurança e validar antes de recarregar

Boas práticas rápidas

• Edite o arquivo correto (geralmente o do site/VirtualHost).
• Faça backup do arquivo antes de mudar.
• Valide a sintaxe antes de recarregar o serviço.
• Se possível, mantenha uma sessão SSH extra aberta para reverter caso algo dê errado.

Validação de sintaxe

Após qualquer mudança, valide:

sudo apachectl configtest

Se retornar Syntax OK, recarregue a configuração (sem derrubar conexões):

sudo systemctl reload apache2

Se der erro, o configtest normalmente aponta arquivo e linha. Corrija antes de recarregar.

ServerName e ServerAlias: identidade do site e roteamento por hostname

Conceito

ServerName define o nome principal do site (hostname) que aquele contexto atende. Em VirtualHosts, ele ajuda o Apache a escolher qual bloco deve responder para um determinado Host (header HTTP). ServerAlias adiciona nomes alternativos (ex.: www, domínios adicionais).

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Exemplo prático em VirtualHost

<VirtualHost *:80>  ServerName exemplo.local  ServerAlias www.exemplo.local exemplo.test  DocumentRoot /var/www/exemplo/public</VirtualHost>

Armadilhas comuns

• ServerName ausente: pode gerar avisos e, em ambientes com múltiplos sites, facilitar que o Apache escolha o VirtualHost “errado” como padrão.
• Conflito de nomes: dois VirtualHosts com o mesmo ServerName (ou alias) criam comportamento imprevisível (geralmente o primeiro carregado “ganha”).
• DNS/hosts não apontando: mesmo com ServerName correto, se o cliente não resolve o hostname para o IP do servidor, você não chega no VirtualHost esperado.

DocumentRoot: a pasta publicada (e o risco de publicar o que não deve)

Conceito

DocumentRoot define o diretório base de onde o Apache servirá arquivos para aquele site. Tudo que estiver dentro dele (e permitido pelas regras de acesso) pode ser entregue ao cliente.

Exemplo

DocumentRoot /var/www/exemplo/public

Armadilhas comuns

• Apontar para a pasta errada: publicar a raiz do projeto (com arquivos sensíveis) em vez de uma pasta public (ou equivalente).
• Permissões e Require: mudar o DocumentRoot sem ajustar o bloco <Directory> correspondente costuma resultar em 403 Forbidden.
• Links simbólicos: se o site usa symlinks, a diretiva Options FollowSymLinks pode ser necessária (com cuidado).

DirectoryIndex: qual arquivo abre quando você acessa “/”

Conceito

DirectoryIndex define a lista de arquivos que o Apache tenta servir quando a URL aponta para um diretório (por exemplo, / ou /docs/). Ele procura na ordem definida e usa o primeiro que existir.

Exemplo

DirectoryIndex index.html index.php

Armadilhas comuns

• Arquivo não existe: se nenhum arquivo da lista existir, o Apache pode retornar 403 (sem listagem) ou listar o diretório (se Indexes estiver habilitado).
• Ordem importa: se você coloca index.html antes de index.php, um index.html antigo pode “ganhar” e esconder a aplicação.

Options: controle de recursos do diretório (Indexes e FollowSymLinks)

Conceito

Options habilita/desabilita funcionalidades em um diretório. Duas opções muito comuns:

• Indexes: permite listagem do conteúdo do diretório quando não há arquivo de índice.
• FollowSymLinks: permite seguir links simbólicos dentro do diretório publicado.

Exemplos típicos

Desabilitar listagem e permitir symlinks (comportamento comum em produção):

<Directory /var/www/exemplo/public>  Options -Indexes +FollowSymLinks</Directory>

Habilitar listagem intencionalmente (útil para um diretório de downloads, por exemplo):

<Directory /var/www/exemplo/public/arquivos>  Options +Indexes</Directory>

Armadilhas comuns

• Exposição por Indexes: habilitar Indexes no lugar errado pode expor backups, arquivos de configuração, dumps, logs e outros artefatos.
• Symlinks sem controle: FollowSymLinks pode permitir que um symlink aponte para áreas inesperadas do sistema. Combine com permissões corretas e escopo bem definido do DocumentRoot.

AllowOverride: quando o .htaccess funciona (e o custo disso)

Conceito

AllowOverride define se arquivos .htaccess dentro de um diretório podem sobrescrever configurações. Quando habilitado, o Apache precisa verificar a existência de .htaccess em cada requisição (impacto de performance) e você abre espaço para mudanças locais que podem surpreender.

Exemplos

Desabilitar completamente (preferível quando você controla o arquivo do site):

<Directory /var/www/exemplo/public>  AllowOverride None</Directory>

Permitir apenas regras específicas (ex.: reescrita), se necessário:

<Directory /var/www/exemplo/public>  AllowOverride FileInfo</Directory>

Armadilhas comuns

• “Minhas regras não funcionam”: geralmente é AllowOverride None no diretório onde está o .htaccess.
• Permitir tudo sem necessidade: AllowOverride All facilita, mas aumenta superfície de erro e pode permitir configurações indesejadas.

Require: quem pode acessar (controle de acesso básico)

Conceito

Require controla autorização. O caso mais comum é permitir acesso público ao conteúdo do site com Require all granted. Também é comum restringir por IP em áreas administrativas.

Exemplos

Permitir acesso público:

<Directory /var/www/exemplo/public>  Require all granted</Directory>

Restringir uma área por IP (exemplo simples):

<Directory /var/www/exemplo/public/admin>  Require ip 192.168.1.0/24</Directory>

Armadilhas comuns

• 403 após mudar DocumentRoot: faltou um bloco <Directory> para o novo caminho com Require all granted (ou regra equivalente).
• Escopo errado: aplicar restrição em um diretório pai pode bloquear tudo sem querer.

Mini-laboratório: trocar DocumentRoot, definir página inicial e controlar listagem de diretórios

Objetivo

• Apontar o site para uma nova pasta (DocumentRoot).
• Definir um DirectoryIndex claro.
• Desabilitar listagem por padrão e habilitar apenas onde for intencional.
• Validar com apachectl configtest e recarregar com segurança.

Passo 1 — Criar a nova estrutura de pastas e arquivos

Crie uma pasta “public” e um diretório de downloads para testar listagem:

sudo mkdir -p /var/www/lab/public/arquivos

Crie uma página inicial e alguns arquivos no diretório de listagem:

echo '<h1>Lab Apache</h1><p>DocumentRoot alterado com sucesso.</p>' | sudo tee /var/www/lab/public/index.html > /dev/null

echo 'arquivo 1' | sudo tee /var/www/lab/public/arquivos/um.txt > /dev/null

echo 'arquivo 2' | sudo tee /var/www/lab/public/arquivos/dois.txt > /dev/null

Ajuste permissões básicas (o Apache precisa ler):

sudo chown -R root:root /var/www/lab

sudo chmod -R 755 /var/www/lab

Passo 2 — Editar o VirtualHost para usar o novo DocumentRoot

No arquivo do seu site (o VirtualHost que você está usando), ajuste/garanta estas diretivas. Exemplo de bloco (adapte ServerName e o caminho do arquivo do site):

<VirtualHost *:80>  ServerName lab.local  ServerAlias www.lab.local  DocumentRoot /var/www/lab/public  DirectoryIndex index.html  <Directory /var/www/lab/public>    Options -Indexes +FollowSymLinks    AllowOverride None    Require all granted  </Directory>  <Directory /var/www/lab/public/arquivos>    Options +Indexes  </Directory></VirtualHost>

O que este exemplo faz:

• Publica apenas /var/www/lab/public (não a raiz do projeto).
• Define index.html como página inicial.
• Bloqueia listagem de diretórios no site inteiro (-Indexes).
• Permite listagem somente em /arquivos (intencional).
• Desabilita .htaccess para previsibilidade (AllowOverride None).
• Garante acesso público ao conteúdo (Require all granted).

Passo 3 — Validar e recarregar

sudo apachectl configtest

Se estiver OK:

sudo systemctl reload apache2

Passo 4 — Verificar o comportamento esperado

• Acesse http://lab.local/ e confirme que a página index.html aparece.
• Acesse http://lab.local/arquivos/ e confirme que a listagem aparece (porque você habilitou +Indexes apenas ali).
• Crie um diretório sem index.html fora de /arquivos e confirme que não há listagem (deve dar 403 ou comportamento equivalente, dependendo de outras configurações).

Passo 5 — Teste de armadilha controlada (para aprender)

Para ver o impacto de DirectoryIndex, altere temporariamente para um arquivo que não existe:

DirectoryIndex inicio.html

Valide e recarregue. Ao acessar /, você observará erro por falta de índice (e sem listagem, porque -Indexes está ativo). Volte para:

DirectoryIndex index.html

Valide novamente com apachectl configtest e recarregue.