Guia: Como instalar o plugin no cPanel/WHM
Objetivo
Instalar o plugin de rastreamento de entrega em um servidor cPanel/WHM, do download até a primeira tela funcionando.
Escopo e Público
- Aplica-se a: servidores cPanel & WHM 11.110 ou mais novo.
- Não cobre: DirectAdmin
(guia próprio), nem a configuração da credencial do relay(guia próprio). - Público-alvo: administrador com acesso root por SSH.
Pré-requisitos
| Item | Exigência |
|---|---|
| cPanel & WHM | 11.110 ou mais novo |
| PHP | 8.1+ — o instalador usa o /usr/local/cpanel/3rdparty/bin/php que já vem no painel |
| Extensões PHP | pdo_sqlite, curl, json, zlib |
| Acesso | root, por SSH |
Você não precisa da credencial de API do relay para instalar.instalar — ela é um passo à parte, descrito em Como configurar a credencial do relay no plugin.
Passos (sequência)
Passo 1 — Baixar o plugin
O plugin é distribuído pelo painel do Sender25. Entre na sua conta, abra Plugin no menu lateral do servidor e você verá a versão publicada, as notas dela e um comando pronto, já com o número da versão, o digest e um código de autorização.
Esse código vale 15 minutos e libera aquele arquivo, não o diretório. Se expirar, volte à página e gere outro — não é erro de permissão.
📷 Espaço para imagem — painel-sender25-pagina-plugin.png
O que precisa aparecer: a página Plugin no painel do Sender25, com o item destacado no menu lateral, a versão publicada, o digest e o comando pronto para copiar.
Onde capturar: app.sender25.com → menu lateral do servidor → Plugin.
O comando tem esta forma (a versão e o digest você copia da página):
curl -fsS 'https://app.sender25.com/plugin/dl/plugin-panel-VERSAO.tar.gz?t=CODIGO' \
-o /tmp/plugin-panel-VERSAO.tar.gz \
&& echo 'DIGEST /tmp/plugin-panel-VERSAO.tar.gz' | sha256sum -c -
⚠ É -o minúsculo, com o nome do arquivo escrito. Com -O maiúsculo, versões de curl anteriores à 7.83 — as que vêm no AlmaLinux 8 e no CentOS 7, por exemplo — colocam o código de autorização dentro do nome do arquivo. O download funciona, o sha256sum seguinte não encontra nada, e o código fica gravado em disco.
O sha256sum -c tem que responder OK. Se não responder, pare: o arquivo não é o que foi publicado.
Passo 2 — Extrair em um diretório próprio
mkdir -p /opt/plugin-panel-VERSAO
tar -xzf /tmp/plugin-panel-VERSAO.tar.gz -C /opt/plugin-panel-VERSAO
⚠ Um diretório por versão, sempre. Extrair uma versão nova por cima da anterior deixa para trás os arquivos que a nova removeu — e o instalador copia tudo que encontra na origem, inclusive as sobras.
Passo 3 — Ver antes o que ele faria
/opt/plugin-panel-VERSAO/scripts/install.sh --dry-run
Imprime cada comando que a execução real faria, sem tocar em nada. Vale sempre: as verificações de pré-requisito (versão do painel, versão do PHP, extensões, se o banco de e-mail é legível) rodam de verdade e se manifestam aqui, antes de qualquer mudança.
Passo 4 — Instalar
flock -w 420 /tmp/sender25-tracking-sync.lock \
-c "/opt/plugin-panel-VERSAO/scripts/install.sh"
O flock só importa em reinstalação ou atualização, e aí importa muito: o coletor roda de minuto em minuto e o instalador troca os arquivos que ele está usando. Sem a trava, um ciclo que caia no meio da troca morre com erro — e você recebe um alerta de rastreamento quebrado por causa de uma instalação que deu certo. Na primeira instalação não há coletor ainda, mas usar sempre custa nada.
O que acontece, em ordem:
- Pré-requisitos — recusa continuar em cPanel abaixo do 11.110, PHP abaixo do 8.1, extensão faltando ou banco de e-mail ilegível.
- Publicação — a aplicação vai para
/opt/sender25-tracking, fora dos docroots do WHM e do cPanel, de modo que nenhuma parte dela é alcançável por HTTP. - Pontos de entrada — instala e registra a tela do WHM e a do cPanel.
- Banco local e agendamento — cria o banco do plugin e agenda o coletor.
- Reinício do
cpsrvd— interrupção breve do acesso web ao WHM e ao cPanel. O fluxo de e-mail não é afetado.
Passo 5 — Abrir a tela
WHM → Plugins → Sender25. Você deve ver uma lista de mensagens — possivelmente vazia, se o servidor enviou pouco e-mail recentemente, mas nunca um erro.
📷 Espaço para imagem — whm-menu-plugins-sender25.png
O que precisa aparecer: o menu do WHM com o grupo Plugins aberto e a entrada Sender25 visível. É onde o leitor vai procurar e não achar se algo deu errado no registro.
Onde capturar: WHM, barra lateral esquerda, após a instalação.
Confira na aba Configurações se o hostname do relay foi detectado sozinho. O instalador tenta adivinhá-lo a partir do /etc/exim.conf; se não achou, informe você mesmo.
Próximos passos: configurar a credencial do relay, que é o que liga o rastreamento de saída, e depois entender os status de entrega. O mapa das telas está em As telas do plugin.
Instalando sem expor ao cliente ainda
/opt/plugin-panel-VERSAO/scripts/install.sh --whm-only
Instala apenas a tela do administrador. Vale a pena num servidor com clientes: a tela do cPanel fica visível para todas as contas no instante em que é registrada, sem opt-in. Com --whm-only você olha a tela primeiro, confere que os dados fazem sentido, e só depois roda o instalador completo para liberar aos clientes.
Problemas comuns
O instalador parou num pré-requisito
É o comportamento pretendido. Instalar num painel cujo contrato de plugin não foi verificado é pior do que não instalar. A mensagem diz exatamente qual item falhou.
O ícone no menu do cliente não apareceu, ou é o antigo
O Jupiter desenha os ícones a partir de uma folha de sprites, não do arquivo em disco. O instalador regenera essa folha, mas se o ícone continuar o anterior, é essa folha que está velha — não o plugin.
A lista aparece vazia
Normal em servidor com pouco envio recente. Envie uma mensagem de teste por uma conta do servidor e procure por ela um ou dois minutos depois.
Controle de Mudanças
Informações de controle de versão
- Última revisão 02-09-2026
- Próxima revisão 02-03-2027
- Autor Sender25
- Versão 1.0