cPanel Skeleton Directory: Arquitetura e

A arquitetura e o motor de provisionamento do diretório skeleton no cPanel (cpanel3-skel)#

Quando criamos novas contas no cPanel ou WHM, o diretório skeleton (cpanel3-skel) parece apenas uma pasta comum usada para copiar e colar arquivos iniciais no novo /home. No entanto, quando descemos ao nível das chamadas de sistema (syscalls) e inspecionamos como o script /scripts/wwwacct lida com quotas, jaulas e permissões, a mecânica se revela muito mais interessante.

Neste artigo, documento o funcionamento interno desse motor de templates no cPanel, como rastrear o comportamento do kernel durante a criação de uma conta com strace e como contornar armadilhas com o VirtFS usando hooks padronizados.

Arquitetura de caminhos e hierarquia de proprietários#

O cPanel usa o diretório skeleton como template base para qualquer criação de conta disparada pelo WHM, pela API ou pelo terminal. O fluxo central é orquestrado pelo utilitário /scripts/wwwacct.

A primeira decisão do binário ao iniciar o provisionamento é identificar quem é o proprietário (owner) da conta:

Contas criadas pelo usuário root: o sistema busca os arquivos de template em /root/cpanel3-skel/.
Contas criadas por revendas (resellers): o sistema mapeia a origem para /home/$reseller/cpanel3-skel/.

Durante a execução, o wwwacct faz uma cópia recursiva desse conteúdo para o diretório de destino recém-criado em /home/$user/. Se pastas obrigatórias da estrutura (como public_html ou os diretórios de e-mail) não existirem dentro do skel, o instalador injeta os padrões do cPanel. Se já existirem, ele realiza uma mesclagem ordenada.

Rastreabilidade e chamadas de sistema no kernel#

Para entender por que um provisionamento falha ou se comporta de forma inesperada, precisamos acompanhar o que o wwwacct (escrito em Perl com chamadas a utilitários compilados) executa no sistema operacional. A rotina de cópia aplica regras semelhantes à função File::Copy::Recursive, mas envelopada para lidar com quotas de disco do Linux e atributos estendidos (xattrs), fundamentais em ambientes como o CageFS do CloudLinux.

Durante a criação da conta, o kernel processa uma sequência direta de syscalls: mkdir() para erguer a árvore de diretórios, seguida de chown() e chmod(). O cPanel assegura que os arquivos de origem, originalmente pertencentes ao root ou ao revendedor, tenham seus metadados reescritos no destino para o par $user:$user.

Depuração com strace no terminal#

Para inspecionar essa rotina em tempo real, costumo rodar o strace filtrando apenas as syscalls de manipulação de arquivos e descritores:

strace -f -e trace=creat,openat,rename,chown /scripts/wwwacct domain.com user pass quota plan

Esse comando é útil por dois motivos:

Flag -f: segue todos os processos filhos (forks). O wwwacct despacha múltiplos subprocessos durante o ciclo de provisionamento.
Filtro -e trace=...: remove o excesso de ruído do terminal. As chamadas creat e openat mostram a abertura física de arquivos no novo /home, enquanto chown confirma o momento exato em que o kernel aplica o UID definitivo do usuário.

Durante o rastreamento, variáveis como $CPANEL_PHP_VERSION e $HOMEDIR também podem ser observadas, já que alteram caminhos de arquivos de configuração do PHP (como .user.ini colocados no skel).

Armadilhas comuns e casos de borda#

Colocar arquivos personalizados no diretório skeleton sem testar o comportamento do instalador pode gerar problemas sutis para a conta do usuário.

O risco do .bashrc e arquivos ocultos#

É comum colocar arquivos de configuração no skel para definir atalhos de terminal ou cabeçalhos de segurança via .htaccess.

No caso do .bashrc, colocar uma versão personalizada dentro de /root/cpanel3-skel/ faz a rotina do wwwacct sobrescrever o arquivo padrão distribuído pelo sistema operacional (/etc/skel/.bashrc). Se o seu arquivo customizado não carregar variáveis de ambiente essenciais do sistema, o usuário pode ter comandos quebrados ao abrir sessões via SSH.

Links simbólicos e a jaula do VirtFS#

Outro ponto de atenção envolve links simbólicos:

Comportamento da cópia: se você incluir um link simbólico dentro do diretório skel, o cPanel copia o próprio link, e não o arquivo de destino apontado por ele.
Problema com caminhos externos: se o alvo do link estiver fora do /home/$user/ (por exemplo, apontando para /var/www/html/assets), o link quebrará dentro da conta. Quando o usuário acessa o shell enjaulado (JailShell/VirtFS), o cPanel restringe a navegação ao namespace montado para aquela conta, impedindo o acesso ao inode externo.

Permissões do public_html e o wwwacct.conf#

O diretório public_html precisa da permissão 0750 para que o servidor web (rodando como usuário nobody ou sob módulo de processo compartilhado) consiga ler seu conteúdo. Se o seu skel contiver um diretório com permissões como 0777 ou 0700, o pós-processamento do wwwacct tentará corrigir o valor com base na diretiva HOMEMATCH configurada em /etc/wwwacct.conf.

Como investigar provisionamentos travados#

Se o provisionamento travar no meio do caminho ou os arquivos do template não aparecerem no /home, a melhor abordagem é consultar os registros do sistema de arquivos em vez de confiar apenas na interface gráfica do WHM.

Arquivos de log mais relevantes:

Erros gerais do cPanel: /usr/local/cpanel/logs/error_log (exibe avisos e falhas em rotinas Perl).
Histórico transacional de contas: /var/cpanel/logs/account_creations.log.

Verificações preventivas no terminal#

Se o script parecer ignorar o skel, o primeiro passo é checar permissões e atributos imutáveis na pasta de origem:

# 1. Conferir acesso de leitura a pasta skeleton
ls -lah /root/cpanel3-skel/

# 2. Checar atributos imutaveis (flag 'i') no diretorio
lsattr /root/cpanel3-skel/

Se o provisionamento congelar indefinidamente, a causa mais provável é espera por I/O (I/O wait). Isso acontece frequentemente quando alguém esquece arquivos pesados (como uma ISO ou um .tar.gz de backup antigo) dentro de /root/cpanel3-skel/, forçando o disco a copiar gigabytes desnecessários a cada nova conta.

Para identificar em qual arquivo a rotina está travada:

# Inspecionar descritores abertos pelo processo do wwwacct
lsof -p $(pgrep -f wwwacct)

O comando lista todos os ponteiros de arquivo abertos, revelando exatamente qual arquivo da árvore está gerando o gargalo de leitura ou escrita.

Automação dinâmica com hooks pós-criação#

A partir da versão 116 do cPanel/WHM, o atalho visual para o cpanel3-skel foi descontinuado na interface gráfica, embora o backend continue processando o diretório normalmente. Para quem gerencia ambientes com muitos pacotes e clientes diferentes, depender de uma pasta estática única tem limitações.

Uma alternativa mais modular é usar os Standardized Hooks do cPanel, executando ações personalizadas logo após a conclusão do wwwacct.

Podemos criar um script de pós-criação em /usr/local/cpanel/scripts/postacctcreate e registrá-lo com o utilitário /usr/local/cpanel/bin/manage_hooks:

#!/bin/bash
# Script de hook pos-criacao para injecao condicional de arquivos

user=$1

# Consulta o pacote atribuido a conta via API do WHM
plan=$(whmapi1 accountsummary user=$user | grep 'plan:' | awk '{print $2}')

# Injeta arquivos seletivos conforme o plano contratado
if [ "$plan" == "Platinum_Tier" ]; then
    rsync -av /opt/templates/platinum/ /home/$user/
    chown -R $user:$user /home/$user/
fi

Essa abordagem permite manter o skel padrão enxuto e aplicar clonagem de repositórios Git, descompactação de estruturas específicas ou injeção de chaves de licença conforme o plano do usuário, sem interferir no fluxo nativo do cPanel.

Do template estático aos hooks: lições práticas de provisionamento#

O diretório skeleton do cPanel é prático para padronizar arquivos básicos, mas exige cuidado com permissões e vínculos de sistema de arquivos. Entender o papel do /scripts/wwwacct, monitorar as chamadas de sistema com strace e isolar symlinks problemáticos evita contas corrompidas logo no primeiro acesso.

Para cenários onde cada tipo de cliente necessita de arquivos ou versões de PHP diferentes, a migração para hooks do tipo postacctcreate oferece controle dinâmico, mantém o tempo de criação de contas rápido e reduz falhas de manutenção no servidor.

Este artigo foi útil?

Deixe uma reação rápida para apoiar o conteúdo:

887 leituras

Creative Commons Atribuição-NãoComercial

Este post está licenciado sob CC BY-NC.