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
- Aplica-se a: servidores DirectAdmin (testado contra o 1.701).
- Não cobre: cPanel/WHM, nem a configuração da credencial do relay.
- Público-alvo: administrador com acesso root por SSH.
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.
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.
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
Figura 3 - Tela para personalizar a skin do DirectAdmin
Passo 2 — Ir para o menu
Na seção Identidade visual, clique no item Menu.
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.
Figura 5 - Desativar o rastreamento de emails nativo
Passo 5 — Acrescentar a entrada do plugin
Adicione um link novo na mesma categoria, apontando para:
/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.
Figura 6 - Adicionar o item no menu do 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.
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






Nenhum comentário para exibir
Nenhum comentário para exibir