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

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

João Rizzon · 2026-10-30 · Servidores

---

## 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](https://docs.cpanel.net/whm/software/multiphp-manager-for-whm-system-settings/):

| 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:

- O valor é **por pool, não por servidor**. Com um pool por domínio, o consumo potencial é `max_children × número de pools ativos`, não `max_children`.
- Mudar o padrão do sistema **não reescreve pools que já foram personalizados**, mas reescreve, no próximo rebuild, todos os que nunca receberam valor próprio. Quem já tem valor próprio continua com o valor próprio.

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:

```bash
# 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.

```bash
# 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:

- **RSS soma memória compartilhada.** Páginas do binário e de bibliotecas aparecem em cada processo. Somar RSS de N filhos superestima o consumo real. Para uma leitura mais honesta por processo, use `PSS` (`/proc/<pid>/smaps_rollup`), que divide a memória compartilhada entre quem a usa:

```bash
# 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.

- **`memory_limit` não é consumo.** Um `memory_limit` de 256M não significa 256 MB por filho; significa o teto que um script pode atingir antes de ser abortado. O que dimensiona o servidor é o RSS/PSS observado, com o `memory_limit` servindo de pior caso.

## 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:

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

## 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:

```bash
# 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:

```bash
/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:

```bash
/opt/cpanel/ea-php82/root/usr/sbin/php-fpm \
  -y /opt/cpanel/ea-php82/root/etc/php-fpm.conf -t
```

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

```bash
# 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.

```bash
# 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

- **Subir o default para resolver lentidão de um site.** Se o gargalo é consulta de banco ou I/O, mais filhos PHP só aumentam a fila e o consumo. Olhe o slow query log e o tempo de resposta antes de mexer aqui: na maioria das vezes em que PHP-FPM parece pequeno, o que está travado está atrás dele.
- **Esquecer que cada versão de PHP tem seus próprios diretórios e seu próprio master.** Um parque com quatro versões ativas tem quatro conjuntos de pools somando memória no mesmo host.
- **Reconstruir sem testar sintaxe.** Um pool inválido pode impedir o start do master daquela versão, derrubando todos os domínios que a usam. Sempre `-t` antes de reload.
- **Tratar `memory_limit` como dimensionamento.** Ele limita o script, não reserva memória; a conta de capacidade é feita com RSS/PSS medido.
- **Não registrar o estado anterior.** Antes de qualquer `--rebuild`, guarde cópia dos YAML de userdata e dos `.conf` gerados. A reversão é copiar de volta e reconstruir.

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

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

