Ir para o conteúdo principal

Guia: Como instalar o plugin no DirectAdmin

Objetivo

Instalar o plugin de rastreamento de entrega em um servidor DirectAdmin, do download até a primeira tela funcionando.


Escopo e Público


Pré-requisitos

Item Exigência
DirectAdmin testado contra o 1.701
PHP 8.1+ em /usr/local/bin/php
Extensões PHP pdo_sqlite, curl, json, zlib e posix
Log de e-mail /var/log/exim/mainlog legível
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

Figura 1 - Página para baixar o plugin no DirectAdmin

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 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-directadmin.sh --dry-run

Imprime cada comando que a execução real faria, sem tocar em nada. As verificações de pré-requisito rodam de verdade aqui, antes de qualquer mudança.

Passo 4 — Instalar
flock -w 420 /tmp/sender25-tracking-directadmin-sync.lock \
  /opt/plugin-panel-VERSAO/scripts/install-directadmin.sh

⚠ Repare que o nome da trava é diferente do cPanel (-directadmin- no meio). Usar o nome errado parece funcionar e não protege nada: você toma uma trava que ninguém disputa.

A trava importa em reinstalação ou atualização: o coletor roda de minuto em minuto e o instalador troca os arquivos que ele está usando. Sem ela, um ciclo que caia no meio da troca morre com erro, e o cron reporta rastreamento quebrado por causa de uma instalação que deu certo.

Nenhum serviço do painel é reiniciado, nem antes nem depois. Diferente do cPanel, aqui não há interrupção alguma — o que torna a instalação em servidor com muitas contas bem menos delicada.

Pode aparecer uma execução do coletor terminando logo depois da instalação. É normal por até um minuto.

Passo 5 — Abrir a tela

Entre no DirectAdmin como administrador e abra o plugin no menu de administração. Você deve ver uma lista de mensagens — possivelmente vazia, se o servidor enviou pouco e-mail recentemente, mas nunca um erro.

 

image.png

Figura 2 - Página do plugin no DirectAdmin

Confira na aba Configurações se o hostname do relay foi detectado sozinho; se não, 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.


Substituindo a tela nativa de rastreamento

O DirectAdmin tem a própria tela de rastreamento: Rastreamento de e-mails, na rota /user/email/tracking, dentro da categoria E-mail Manager do menu do cliente. Instalar o plugin não mexe nela — as duas passam a existir lado a lado, e o cliente fica com dois lugares que parecem responder à mesma pergunta.

A troca é feita no próprio painel, na personalização de skin. O plugin não escreve nada nessa área: quem desabilita a entrada nativa e cria a nova é você, pela tela do DirectAdmin, e é por isso que dá para desfazer sem desinstalar nada.

O instalador põe a tela no ar, mas não a põe em menu nenhum. Sem os passos abaixo, o plugin funciona e ninguém o encontra — só chega quem digitar a URL. Esta seção é a outra metade da instalação.

Passo 1 — Abrir a personalização de skin

No menu de administração, abra Personalizar Skin <skin-atual>.

image.png


Figura 3 - Tela para personalizar a skin do DirectAdmin

Passo 2 — Ir para o menu

Na seção Identidade visual, clique no item Menu.

image.png


Figura 4 - Item "Menu" na tela de personalização

Passo 3 — Achar a categoria certa

Dentro da tela de personalização do menu do usuário, localize a seção E-mail Manager. É a categoria onde a entrada nativa vive, e é onde a nova precisa nascer para ficar no lugar dela.

Passo 4 — Desabilitar a tela nativa

Desabilite o recurso nativo de rastreamento de e-mails do DirectAdmin — user/email/tracking. Ele fica desabilitado, não removido: religar é marcar de volta.

image.png

Figura 5 - Desativar o rastreamento de emails nativo

Passo 5 — Acrescentar a entrada do plugin
/plugin?src=%2FCMD_PLUGINS%2Femailtracking

Por que a URL tem essa cara. A URL de verdade do plugin é /CMD_PLUGINS/emailtracking, e ela funciona num link comum. Mas um href de item de menu é resolvido pelo roteador interno do painel, que não conhece endereços legados e responde 404. O /plugin?src= é a rota do próprio DirectAdmin que embrulha um endereço legado dentro da interface — a URL real vai no parâmetro src, codificada. Copie a linha acima exatamente como está.

O ícone. Essa mesma tela aceita uma imagem para a entrada. Vale usar: é o que faz a troca ficar invisível para o cliente, em vez de parecer que sumiu uma coisa e apareceu outra.

image.png

[ESPAÇO PARA PRINT — Figura 3]6 A- telaAdicionar deo personalizaçãoitem deno menu, com a categoria E-mail Manager aberta, mostrando a entrada nativa desabilitada e a nova entradamenu do plugin ao lado. Anonimizar: nome do servidor e qualquer nome de conta visíveis no cabeçalho.usuário

Conferindo

Entre em uma conta de cliente — não a sua de administrador — e abra o menu E-mail. Deve haver uma entrada só de rastreamento, e ela deve abrir a tela do plugin.

Confira também numa conta que use CrossBox, se você tiver: o CrossBox grava a própria personalização de menu, e a combinação das duas não foi testada.

Antes de sair avisando os clientes

O acesso ao plugin é controlado pelo plugins_allow de cada conta. A entrada de menu que você acabou de criar é um link comum e não conhece essa regra — ela aparece para todo mundo. Numa conta que não libere o plugin, o item vai estar no menu e a tela não vai abrir, que é pior do que não aparecer.

Para ver quais contas ficariam assim:

grep -LE '^plugins_allow=(.*:)?emailtracking(:|$)' \
  /usr/local/directadmin/data/users/*/user.conf 2>/dev/null \
  | xargs -r -n1 dirname | xargs -r -n1 basename

Contas sem nenhuma linha plugins_allow são irrestritas e não aparecem no resultado. Atenção a um detalhe que engana: alterar o pacote não corrige contas já existentes — o user.conf delas guarda o valor de quando foram criadas. Reaplique o pacote nessas contas. A opção para permitir que os clientes acessem o plugin efetivamente é em "Permitir/bloquear Plugins" ( exemplo: https://<host-directadmin>/<skin>/reseller/users/<usuário>/modify)

Desfazendo

Volte à mesma tela, reabilite a entrada nativa e apague a que você criou. Nada do plugin precisa ser tocado, e desinstalar o plugin não desfaz essa troca — a personalização de menu é do painel, não dele.


Instalando sem expor ao cliente ainda

/opt/plugin-panel-VERSAO/scripts/install-directadmin.sh --admin-only

Instala apenas a tela do administrador. A tela do cliente fica alcançável por qualquer conta no instante em que os arquivos dela existem, sem opt-in — então escalonar mantém a primeira olhada entre você e o servidor.


Problemas comuns

O instalador parou num pré-requisito

É o comportamento pretendido. A mensagem diz exatamente qual item falhou — versão do PHP, extensão ausente ou mainlog ilegível.

A tela do cliente não aparece no painel dele

Quase sempre é porque nada aponta para ela: o instalador põe a tela no ar mas não cria entrada de menu nenhuma. O conserto é a seção Substituindo a tela nativa de rastreamento, acima.

As outras duas causas: se você instalou com --admin-only, a tela do cliente não foi instalada; e se a conta não libera emailtracking no plugins_allow, a tela existe mas o painel nega o acesso àquela conta.

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