blog
Servidores

max_children no PHP-FPM do WHM: como calcular o default

Onde fica o pool default no WHM, como calcular max_children a partir da RAM que o servidor tem de fato e por que contas com pool personalizado ignoram esse padrão.

JR · · 9 min de leitura · 1 tabela · 9 blocos de código

Resposta curta: não existe um número universal. O valor correto de `pm.max_children` no pool default do WHM sai de uma conta: RAM total menos MySQL, Exim/Dovecot, kernel e folga, dividido pelo RSS médio medido de um processo php-fpm do seu próprio servidor.

Neste artigo
  1. O que a tela "System PHP-FPM Configuration" realmente define
  2. Por que a multiplicação de pools vende memória que a máquina não tem
  3. Como medir o RSS e o PSS de um filho php-fpm no seu servidor
  4. Dimensionar max_children a partir da RAM real
  5. Onde o valor mora, e por que contas antigas não mudam
  6. Conferir, numa conta real, qual valor acabou valendo
  7. Cinco erros que custam caro nessa configuração
  8. Checklist de aplicação, do pico medido ao pool conferido

O que a tela "System PHP-FPM Configuration" realmente define

No WHM, em Home » Software » MultiPHP Manager, existe uma aba de configuração de sistema do PHP-FPM. Ela não é uma configuração global aplicada em tempo real: é o molde do pool que o cPanel usa ao gerar o arquivo de pool de qualquer domínio que não tenha valores próprios no userdata, seja ele novo ou antigo. A cada --rebuild, todo pool sem personalização é reescrito com o default vigente; só os domínios com YAML próprio ficam imunes. Os três campos são repasses diretos de diretivas do PHP-FPM, segundo a documentação do cPanel:

Campo no WHM Diretiva no pool O que controla
Max Children pm.max_children Teto de processos filhos simultâneos daquele pool (por domínio)
Max Requests pm.max_requests Quantas requisições um filho atende antes de ser reciclado
Process Idle Timeout pm.process_idle_timeout Segundos que um filho ocioso sobrevive antes de ser encerrado

Duas consequências práticas, e são elas que fazem o ajuste valer a pena:

Os pools que o cPanel gera vêm com pm = ondemand, por isso process_idle_timeout existe na tela. Isso não está na página de System Settings: confira no arquivo gerado, grep '^pm *=' /opt/cpanel/ea-php*/root/etc/php-fpm.d/*.conf. Em ondemand, não há filhos pré-aquecidos: eles nascem sob requisição e morrem após o timeout de ociosidade. Isso muda o cálculo de risco, como está adiante.

Por que a multiplicação de pools vende memória que a máquina não tem

O risco não está no número que vem de fábrica, está na multiplicação. Qualquer max_children por pool, multiplicado por dezenas ou centenas de domínios com PHP-FPM habilitado, produz um teto agregado que nenhuma máquina de hospedagem compartilhada tem RAM para honrar. Antes de discutir se o valor é alto ou baixo, leia o que está vigente no seu servidor e some:

# default do sistema, como o cPanel o gravou
grep -RiE 'children|requests|idle' /var/cpanel/ApachePHPFPM/

# teto agregado hoje, somando todos os pools de todas as versões
grep -h 'pm.max_children' /opt/cpanel/ea-php*/root/etc/php-fpm.d/*.conf \
  | awk -F= '{s+=$2} END {if(NR) print "soma=" s, "pools=" NR; else print "nenhum pool"}'

Compare soma com a RAM da máquina dividida pelo RSS medido por filho. É essa razão, e não o valor isolado do default, que diz se a conta fecha.

Na prática isso costuma não estourar porque poucos pools ficam no teto ao mesmo tempo, e porque ondemand derruba filhos ociosos. Mas é overcommit: o teto agregado é uma promessa que depende de os picos nunca coincidirem. Quando coincidem, o que acontece não é um 503 limpo em um site, é OOM killer matando MySQL ou o próprio php-fpm master, ou swap thrashing que degrada tudo ao mesmo tempo.

O ajuste correto não é "aumentar o default" nem "diminuir o default". É escolher o default a partir da RAM real da máquina, sabendo quanto um processo PHP do seu stack ocupa de verdade.

Como medir o RSS e o PSS de um filho php-fpm no seu servidor

Não use estimativa de internet. Meça no seu servidor, com a sua versão de PHP, as suas extensões e as suas aplicações.

# RSS, em KB, de cada processo filho de php-fpm
ps -o rss=,cmd= -C php-fpm | grep 'pool '

# média e máximo de RSS (KB) dos filhos, em uma linha
ps -o rss=,cmd= -C php-fpm | grep 'pool ' \
  | awk '{s+=$1; if($1>m) m=$1} END {if(NR) print "media_kb=" s/NR, "max_kb=" m, "n=" NR; else print "nenhum filho vivo"}'

O filtro grep 'pool ' não é cosmético: -C php-fpm casa também o php-fpm: master process (...) de cada versão de PHP instalada. O master não atende requisição, não escala com pm.max_children e tem RSS próprio (menor que o de um filho com a aplicação carregada). Deixá-lo na amostra puxa a média para baixo e infla o teto agregado que você vai calcular. Em host com quatro versões ativas, são quatro masters contaminando a conta.

Colete isso em horário de pico, não às 4h da manhã. E repita por versão de PHP: um ea-php74 com poucas extensões e um ea-php82 com OPcache, imagick e um framework pesado não ocupam o mesmo espaço.

Duas armadilhas de leitura:

# exige kernel 4.14+ (smaps_rollup) e leitura como root
for p in $(pgrep -f 'php-fpm: pool'); do
  awk '/^Pss:/ {print $2}' /proc/$p/smaps_rollup 2>/dev/null
done | awk '{s+=$1} END {if(NR) print "pss_total_kb=" s, "pss_medio_kb=" s/NR, "n=" NR; else print "sem amostras: kernel sem smaps_rollup, sem permissao ou nenhum filho vivo"}'

Se sair "sem amostras", confirme com ls /proc/1/smaps_rollup antes de culpar o pool: em kernel anterior ao 4.14 o arquivo não existe e a alternativa é somar Pss de /proc/<pid>/smaps, bem mais caro.

Dimensionar max_children a partir da RAM real

O método é subtrativo: tire da RAM total tudo que não é PHP, reserve folga, e divida o que sobra.

RAM_para_PHP = RAM_total
             - MySQL/MariaDB (innodb_buffer_pool_size + buffers por conexão)
             - Exim + Dovecot + antispam
             - kernel, page cache útil, cPanel/WHM, backup
             - folga de segurança

max_children_agregado = RAM_para_PHP / RSS_medio_por_processo

Exemplo fictício, apenas para mostrar a conta: numa máquina de 32 GB, supondo 10 GB atribuídos ao MySQL, 4 GB a mail e serviços de sistema e 4 GB de folga, sobram 14 GB para PHP. Com um RSS médio hipotético de 70 MB por filho, o teto agregado seria por volta de 200 processos PHP simultâneos. Esses números são ilustrativos: os seus saem dos comandos da seção anterior.

Do teto agregado para o max_children do pool default, duas decisões:

  1. Qual fator de sobrecompromisso você aceita. Com ondemand, um fator maior que 1 é defensável, porque filhos ociosos morrem. Fator 1 (soma dos pools ≤ teto agregado) só cabe em servidor com poucos domínios.
  2. Quem foge da regra. O pool default existe para a cauda de contas pequenas. Sites que realmente precisam de concorrência recebem pool personalizado, fora do default.

Uma regra operacional que funciona: mantenha o default baixo o suficiente para que um único domínio sob ataque ou sob crawler agressivo não consiga, sozinho, consumir a memória destinada a todos; e eleve caso a caso o que precisar.

Para que servem Max Requests e Process Idle Timeout

max_requests existe para conter vazamento de memória em extensões e aplicações: o filho é reciclado depois de N requisições, devolvendo RSS ao sistema. Valor muito baixo gera fork constante e perde o aquecimento de OPcache; muito alto deixa o filho inchar. Se o seu RSS medido cresce ao longo do dia, esse é o botão.

process_idle_timeout é o que torna o ondemand seguro: quanto menor, mais rápido a memória volta; quanto maior, menos cold start. Em servidor com muitos domínios de tráfego esporádico, um timeout curto é o que impede que o pico de todos os pools fique residente ao mesmo tempo.

Da RAM total ao max_children do pool defaultRAM totalMemoria fisica da maquinaSubtrair servicosBanco, mail, sistema, folgaRAM para PHPSobra disponivel aos filhosDividir por RSS/PSSValor medido em picoTeto agregadoProcessos PHP simultaneos possiveismax_children do defaultTeto agregado dividido pelos pools
Metodo subtrativo: o default sai da RAM real, nao de estimativa. Cada etapa usa valores medidos no proprio servidor, por versao de PHP.

Onde o valor mora, e por que contas antigas não mudam

O padrão do sistema fica em um YAML de defaults de pool, sob /var/cpanel/ApachePHPFPM/. As personalizações por domínio ficam no userdata, um YAML por domínio:

# default do sistema (o que a tela do WHM edita)
ls -l /var/cpanel/ApachePHPFPM/

# pools personalizados por domínio
ls -l /var/cpanel/userdata/<usuario>/*.php-fpm.yaml
cat /var/cpanel/userdata/<usuario>/exemplo.com.br.php-fpm.yaml

# arquivo de pool efetivamente gerado, por versão de PHP
ls /opt/cpanel/ea-php*/root/etc/php-fpm.d/

A precedência, verificável no .conf gerado depois de um --rebuild: o valor do domínio vence o default do sistema. Alterar a tela de System Settings e reconstruir regenera os pools de todos os domínios sem YAML próprio, incluindo contas antigas, e não sobrescreve domínios que já têm YAML próprio. Se o seu objetivo é padronizar um parque inteiro já existente, mexer só no default resolve apenas a parte não personalizada: para o restante é preciso tratar os YAML por domínio, um a um, e aceitar que cada edição é uma decisão sobre aquele site.

Reconstruir os pools e testar a sintaxe antes do reload

Depois de salvar o novo default, os arquivos de pool precisam ser regerados e o serviço recarregado:

/usr/local/cpanel/scripts/php_fpm_config --rebuild
/usr/local/cpanel/scripts/restartsrv_apache_php_fpm restart

Verifique a sintaxe antes de confiar no reload, por versão de PHP:

/opt/cpanel/ea-php82/root/usr/sbin/php-fpm \
  -y /opt/cpanel/ea-php82/root/etc/php-fpm.conf -t
Aplicar o novo default sem derrubar o masterSalvar defaultSystem PHP-FPM ConfigurationBackupCopiar userdata e .conf geradosRebuildphp_fpm_config --rebuildTestar sintaxephp-fpm -y ... -t por versaoReloadrestartsrv_apache_php_fpm restart
Ordem de aplicacao. O teste de sintaxe antes do reload evita que um pool invalido impeca o start do master e derrube todos os dominios daquela versao.

Conferir, numa conta real, qual valor acabou valendo

O único teste que importa é olhar o arquivo de pool gerado e a contagem de processos vivos.

# o que o pool do domínio realmente recebeu
grep -E 'max_children|max_requests|idle_timeout' \
  /opt/cpanel/ea-php82/root/etc/php-fpm.d/exemplo.com.br.conf

# teto agregado configurado em todos os pools, todas as versões
grep -h 'pm.max_children' /opt/cpanel/ea-php*/root/etc/php-fpm.d/*.conf \
  | awk -F= '{s+=$2} END {print "soma_max_children=" s, "pools=" NR}'

# processos vivos agora, por pool
ps -o cmd= -C php-fpm | grep 'pool ' | sort | uniq -c | sort -rn | head

Compare soma_max_children com o teto agregado que você calculou a partir da RAM. A diferença é, em números, o tamanho do cheque que a máquina assinou e pode não conseguir pagar.

Quando um pool bate no teto, o master emite em nível WARNING a linha WARNING: [pool exemplo.com.br] server reached pm.max_children setting (N), consider raising it. É o sinal mais barato de que aquele domínio específico precisa de pool próprio, e não de aumento do default para todo mundo. O aviso vai para o error_log configurado no pool, não necessariamente para o log global: descubra o caminho antes de procurar.

# onde cada pool escreve
grep -hE '^(error_log|php_admin_value\[error_log\])' \
  /opt/cpanel/ea-php*/root/etc/php-fpm.d/*.conf

# o aviso, no log do master de cada versão
grep -i 'reached pm.max_children' /opt/cpanel/ea-php*/root/usr/var/log/php-fpm.log

Grep vazio não prova ausência de saturação. Se o log_level do master (em php-fpm.conf) estiver em error ou acima, o WARNING nunca é gravado: confirme com grep -h log_level /opt/cpanel/ea-php*/root/etc/php-fpm.conf e volte para notice ou warning antes de concluir que está tudo bem.

Cinco erros que custam caro nessa configuração

Checklist de aplicação, do pico medido ao pool conferido

  1. Medir RSS/PSS dos filhos php-fpm em pico, por versão de PHP.
  2. Calcular a RAM disponível para PHP subtraindo banco, mail, sistema e folga.
  3. Dividir pelo RSS/PSS médio para chegar ao teto agregado de processos.
  4. Escolher o max_children do default, considerando o fator de sobrecompromisso que o modo ondemand permite.
  5. Definir max_requests pela evidência de crescimento de RSS e process_idle_timeout pela urgência de devolver memória.
  6. Salvar em WHM » MultiPHP Manager » System PHP-FPM Configuration, reconstruir e testar sintaxe.
  7. Conferir o .conf gerado de um domínio sem personalização, novo ou antigo, e somar pm.max_children de todos os pools.
  8. Tratar separadamente os domínios com pool personalizado, que o default não alcança.

Referências

  1. Documentação oficial (cpanel) — MultiPHP Manager for WHM - System Settings. Consultado em 2026-10-29.
Leia também