Como criar e configurar templates de DNS no HestiaCP

O provisionamento eficiente e padronizado de zonas de DNS é um pilar central para qualquer provedor de hospedagem de sites ou administrador de sistemas. No ecossistema do HestiaCP, o painel gerencia a criação de registros DNS por meio de arquivos de template (extensão .tpl). Esses modelos automatizam a inserção de apontamentos cruciais (como registros A, MX, TXT e CNAME) no momento em que um domínio é adicionado a uma conta.

Neste guia técnico de infraestrutura, disseco o funcionamento e a anatomia dos templates de DNS no HestiaCP, detalhando a localização física dos arquivos, o mapeamento de variáveis, o passo a passo para criar e aplicar templates customizados, e as rotinas de validação e troubleshooting recomendadas para produção.

1. Localização e funcionamento sob o capô#

Os templates de DNS no HestiaCP funcionam como esqueletos estruturados. Quando uma nova zona é adicionada (seja via interface gráfica, linha de comando ou chamadas de API de sistemas externos de faturamento), o HestiaCP lê o arquivo .tpl selecionado, substitui as variáveis coringa pelos valores reais do servidor e grava as diretivas nos arquivos de zona correspondentes gerenciados pelo servidor DNS BIND9.

Todos os templates do sistema e de usuários ficam armazenados no seguinte diretório:

/usr/local/hestia/data/templates/dns/

Para compreender os limites de edição e variáveis aceitas pelo parseador interno do HestiaCP, você pode consultar o arquivo README localizado na pasta:

cat /usr/local/hestia/data/templates/dns/README

2. Catálogo de modelos DNS nativos do HestiaCP#

O painel vem pré-configurado com modelos voltados para diferentes cenários operacionais:

• child-ns.tpl: Define servidores de nomes filhos (Glue Records) apontando para os subdomínios ns1.seu-dominio.com e ns2.seu-dominio.com usando registros A de forma automatizada.
• default-nomail.tpl: Configura os registros DNS básicos de navegação (como A, CNAME e TXT), mas omite registros MX, desabilitando o recebimento de e-mails diretamente no servidor local.
• default.tpl: O modelo padrão e mais comum. Ele define os apontamentos de navegação e configura os registros de MX locais para que o servidor processe os e-mails do domínio.
• gmail.tpl: Um template focado em integrações Cloud, preenchendo automaticamente os registros de MX apontando para os servidores do Google Workspace (antigo G Suite).
• office365.tpl: Configura de forma ágil os registros de MX e registros TXT (como verificações SPF e MS-token) exigidos para validar a entrega de e-mails no Microsoft Office 365.
• zoho.tpl: Automatiza os apontamentos de MX e registros TXT necessários para o serviço corporativo Zoho Mail.

3. O papel estratégico do template vazio (blank.tpl)#

Um dos modelos mais importantes no HestiaCP em ambientes de produção é o blank.tpl. Ao contrário dos demais, esse arquivo não possui qualquer registro interno, gerando uma zona de DNS vazia.

Essa estrutura é essencial em fluxos de integração com painéis de faturamento e automação como o WHMCS. No pacote padrão dns_only, o blank.tpl atua como template ativo. Quando o cliente compra um domínio e a conta é criada no HestiaCP, o WHMCS cria a zona sem registros pré-configurados.

Isso impede conflitos de roteamento: se o cliente for utilizar um serviço de e-mail externo (como Office 365 ou Google Workspace) ou apontar o site para um servidor CDN externo (Cloudflare), a zona não conterá registros A ou MX apontando para o IP do servidor Hestia local, evitando "loops" de e-mail internos e propagação de registros incorretos.

4. Anatomia de um registro no arquivo de template#

Cada linha dentro de um arquivo .tpl representa um registro de DNS específico estruturado com variáveis e parâmetros delimitados. Os atributos aceitos pelo parseador são:

5. Recomendações de segurança e customização#

Regras de ouro#

1. > [!WARNING]

NUNCA edite os templates nativos do HestiaCP (como default.tpl ou gmail.tpl). Eles são considerados arquivos principais do sistema e podem ser totalmente sobrescritos e restaurados ao padrão do HestiaCP durante atualizações do painel de controle. Para qualquer personalização, crie um arquivo com nome único (ex: meu-template.tpl).

1. Utilização do Ponto Final: Ao preencher valores textuais de FQDNs (nomes de domínios completos) em registros CNAME ou MX (ex: %domain%. ou mail.domain.com.), certifique-se de incluir o ponto final (.) ao fim do nome. Sem ele, o servidor de nomes BIND9 anexará o domínio principal recursivamente, gerando apontamentos inválidos (ex: mail.domain.com.domain.com).
2. Rotina de Backup Preventivo: Antes de realizar modificações ou criar novos templates, crie backups do arquivo individual ou, idealmente, do diretório completo de templates DNS:

    # Backup completo do diretório de templates DNS em tar.gz
    sudo tar czf /root/backup-dns-templates-$(date +%Y%m%d).tar.gz /usr/local/hestia/data/templates/dns/
    
    # Backup de um template individual via caminho absoluto
    sudo cp -p /usr/local/hestia/data/templates/dns/default.tpl /usr/local/hestia/data/templates/dns/default.tpl.bak

6. Criando um template DNS customizado do zero#

Para criar e implantar o seu próprio conjunto padronizado de registros DNS:

Passo 1: Criar o arquivo de template#

Crie um novo arquivo .tpl no diretório de templates com um nome exclusivo:

sudo nano /usr/local/hestia/data/templates/dns/meu-template.tpl

Passo 2: Definir o conteúdo do template#

Insira a estrutura completa de registros respeitando os campos exigidos. Abaixo está um exemplo completo e funcional de template customizado que você pode copiar e modificar:

ID='1' RECORD='@' TYPE='A' PRIORITY='' VALUE='%ip%' TTL='300' SUSPENDED='no' TIME='%time%' DATE='%date%'
ID='2' RECORD='www' TYPE='CNAME' PRIORITY='' VALUE='%domain%.' TTL='300' SUSPENDED='no' TIME='%time%' DATE='%date%'
ID='3' RECORD='mail' TYPE='A' PRIORITY='' VALUE='%ip%' TTL='300' SUSPENDED='no' TIME='%time%' DATE='%date%'
ID='4' RECORD='@' TYPE='MX' PRIORITY='10' VALUE='mail.%domain%.' TTL='300' SUSPENDED='no' TIME='%time%' DATE='%date%'
ID='5' RECORD='@' TYPE='TXT' PRIORITY='' VALUE='v=spf1 a mx ip4:%ip% -all' TTL='300' SUSPENDED='no' TIME='%time%' DATE='%date%'
ID='6' RECORD='ftp' TYPE='CNAME' PRIORITY='' VALUE='%domain%.' TTL='300' SUSPENDED='no' TIME='%time%' DATE='%date%'

Salve e feche o arquivo (Ctrl+O, Enter, Ctrl+X no nano).

Passo 3: Ajustar permissões e propriedades do arquivo#

Para que o painel consiga ler o arquivo de forma segura, defina as permissões corretas (proprietário root e permissão de leitura global 644):

sudo chown root:root /usr/local/hestia/data/templates/dns/meu-template.tpl
sudo chmod 644 /usr/local/hestia/data/templates/dns/meu-template.tpl

Passo 4: Verificar se o template foi reconhecido#

Liste o diretório de templates do HestiaCP para confirmar as permissões e a presença do arquivo:

ls -la /usr/local/hestia/data/templates/dns/

O retorno deve listar o seu novo template meu-template.tpl com permissões 644.

7. Como aplicar o template customizado#

A. Na criação de um novo domínio#

• Pela Interface Gráfica (GUI): Ao adicionar um novo domínio DNS no painel, localize o campo de seleção DNS Template e selecione o seu modelo recém-criado.
• Pela Linha de Comando (CLI): Crie o domínio com suporte a DNS habilitado (yes) e aplique o template com o utilitário do HestiaCP:

    v-add-web-domain usuario dominio.com.br 1.2.3.4 yes
    v-change-dns-domain-tpl usuario dominio.com.br meu-template

B. Em um domínio existente#

Se você precisa aplicar as regras do novo template a uma zona de DNS criada anteriormente, utilize o comando CLI do painel para efetuar a alteração e recriar os registros:

# Alterar o template associado ao domínio
v-change-dns-domain-tpl usuario dominio.com.br meu-template

# Recarregar as configurações de rede do BIND9 para propagar os novos registros
sudo systemctl reload bind9
# ou usando o painel do próprio BIND:
sudo rndc reload

8. Validação e resolução de problemas (troubleshooting)#

Validação do arquivo de template#

Antes de aplicar em produção, verifique a sintaxe estrutural das linhas para garantir que nenhum atributo obrigatório está ausente:

# Validar se as linhas seguem a sintaxe esperada
grep -E "^ID=.*RECORD=.*TYPE=.*VALUE=" /usr/local/hestia/data/templates/dns/meu-template.tpl

Troubleshooting de problemas comuns#

9. Script de automação de backup e validação de templates#

Para administradores que gerenciam infraestruturas de múltiplos servidores, o script shell abaixo automatiza a triagem, o backup e a validação de formatação de todos os templates de DNS presentes no diretório do HestiaCP:

#!/bin/bash
# dns_template_manager.sh - Gerenciamento seguro de templates DNS no HestiaCP
# ⚠️ Deve ser executado com privilégios de root (sudo)

set -e

TEMPLATE_DIR="/usr/local/hestia/data/templates/dns"
BACKUP_DIR="/root/dns-backup-$(date +%Y%m%d-%H%M%S)"

# Cores para saída no terminal
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'

log() { echo -e "${GREEN}[INFO]${NC} $1"; }
warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }

# 1. Verificar privilégios de root
[[ $EUID -ne 0 ]] && error "Este script deve ser executado como root (sudo)"

# 2. Criar backup completo do diretório de templates
log "Criando backup completo dos templates atuais..."
mkdir -p "$BACKUP_DIR"
cp -r "$TEMPLATE_DIR"/* "$BACKUP_DIR/"
log "Backup salvo com sucesso em: ${BACKUP_DIR}"

# 3. Listar templates disponíveis
log "Templates encontrados no sistema:"
ls -la "$TEMPLATE_DIR"/*.tpl 2>/dev/null || warn "Nenhum template .tpl encontrado"

# 4. Validar formato estrutural das linhas
log "Iniciando validação de formatação dos templates..."
for tpl in "$TEMPLATE_DIR"/*.tpl; do
    if [[ -f "$tpl" ]]; then
        TOTAL_LINES=$(wc -l < "$tpl")
        # Conta linhas que seguem o padrão esperado
        VALID_LINES=$(grep -c "^ID=.*RECORD=.*TYPE=.*VALUE=" "$tpl" || true)
        # Conta linhas inválidas (ignorando linhas em branco)
        INVALID_LINES=$(grep -cv "^ID=.*RECORD=.*TYPE=.*VALUE=\|^$" "$tpl" || true)
        
        if [[ $INVALID_LINES -gt 0 ]]; then
            warn "  ⚠️ $(basename "$tpl"): $VALID_LINES linhas válidas, $INVALID_LINES linhas fora do padrão detectadas!"
        else
            log "  ✅ $(basename "$tpl"): $VALID_LINES linhas válidas de registros."
        fi
    fi
done

log "Processo de auditoria concluído."

Veja também

Infraestrutura Como liberar novos servidores no cluster de DNS do HestiaCP

Infraestrutura Como alterar o tempo de transferência de zonas DNS no HestiaCP

Infraestrutura DirectAdmin: como recriar zonas DNS via CLI (o guia de sobrevivência)

Este post está licenciado sob CC BY-NC.