Ir para o conteúdo principal

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


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

📷image.png

EspaçoFigura 1 - Página para imagembaixar —o painel-sender25-pagina-plugin.png
O que precisa aparecer: a página Pluginplugin 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.WHM/cPanel

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:

  1. 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.
  2. 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.
  3. Pontos de entrada — instala e registra a tela do WHM e a do cPanel.
  4. Banco local e agendamento — cria o banco do plugin e agenda o coletor.
  5. 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.

📷image.png

EspaçoFigura para imagem — whm-menu-plugins-sender25.png
O que precisa aparecer:2 o- menuPágina 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 erradoplugin no registro.
Onde capturar: WHM, barra lateral esquerda, após a instalação.WHM

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 (tema do WHM/cPanel) 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