API DNS - Gerenciamento de Domínios

Visão Geral

A API DNS permite o gerenciamento de domínios autoritativos e verificação de estatísticas do DNS recursivo no Ravi Monitor.

Parâmetros Base

Todas as operações DNS requerem:

action=dns
operation: Operação específica
token: Token com permissão dns

Parâmetro Global Opcional: `defer_reload`

Operações que modificam dados (add_domain, add_subdomain, delete_subdomain, delete_domain) por padrão disparam reload automático do NSD ao final da operação.

Se você precisa fazer várias mudanças em sequência (ex: criar 30 registros de uma vez), passe defer_reload=1 em todas as N chamadas e depois chame uma única operation=reload_nsd no final. Isso evita N reloads do NSD pra N mudanças.

# 30 mudanças sem reload individual
curl ... -d "operation=add_subdomain" ... -d "defer_reload=1"
curl ... -d "operation=add_subdomain" ... -d "defer_reload=1"
# ... mais 28 ...
# 1 reload consolidado no final
curl ... -d "operation=reload_nsd"

Operações Disponíveis

1. recursive - Estatísticas do DNS Recursivo

Retorna estatísticas detalhadas do serviço DNS recursivo (Unbound).

Exemplo de Requisição

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=recursive"

Resposta

{
  "recursive": {
    "service_status": {
      "unbound_active": true,
      "unbound_enabled": true
    },
    "current_metrics": {
      "queries_per_second": 12.5,
      "avg_response_time": 45.2,
      "cache_hit_ratio": 85.3,
      "total_num_queries": 15420
    },
    "query_types": {
      "A": 8500,
      "AAAA": 3200,
      "PTR": 1800
    },
    "security_metrics": {
      "dnssec_validated": 12000,
      "dnssec_bogus": 15
    },
    "blocklists": {
      "adware_malware": 25000,
      "phishing": 8500
    }
  }
}

2. authoritative - Listar Domínios Autoritativos

Lista todos os domínios autoritativos ou dados de um domínio específico.

Parâmetros Opcionais

domain (ou dom): Domínio específico para consultar

Exemplo 1: Todos os Domínios

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=authoritative"

Exemplo 2: Domínio Específico

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=authoritative" \
  -d "domain=exemplo.com"

Resposta

{
  "authoritative": [
    {
      "id": 1,
      "domain": "exemplo.com",
      "entries": [
        {
          "id": 1,
          "name": "www",
          "value": "192.168.1.100",
          "type": "A",
          "host": null,
          "priority": null,
          "alt_domain": null
        },
        {
          "id": 2,
          "name": "@",
          "value": "10 mail.exemplo.com.",
          "type": "MX",
          "host": null,
          "priority": 10,
          "alt_domain": null
        }
      ]
    }
  ]
}

Nota sobre o schema (importante):

Records criados via API (add_subdomain): name = label do sub (ex: www, @, m1.smtp01), value = destino (IP/hostname), host = null.

Records criados via UI legada do painel: name = null, value = label do sub, host = destino. Semântica trocada.

Sempre prefira gravação via API. Para leitura, detecte qual schema está sendo usado pela presença de name.

Campo priority é populado apenas para registros MX/SRV.

3. add_domain - Adicionar Domínio

Adiciona um novo domínio autoritativo ao sistema.

Parâmetros Obrigatórios

domain (ou dom): Nome do domínio

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=add_domain" \
  -d "domain=novodominio.com"

Resposta de Sucesso

{"msg": "ok"}

Resposta de Erro

{"msg": "Domain already exists"}

4. add_subdomain - Adicionar Subdomínio

Adiciona um novo registro DNS a um domínio existente.

Parâmetros Obrigatórios

domain (ou dom): Domínio
subdomain (ou subdom): Nome do subdomínio
type (ou tipo): Tipo do registro (A, AAAA, CNAME, etc.)
host: IP ou hostname de destino

Parâmetros Opcionais

comment: Comentário sobre o registro
priority (ou prioridade): Prioridade numérica para registros MX ou SRV. Ex: 10, 20. Ignorado em outros tipos.
adicional (ou alt_domain): Domínio alternativo para registros PTR. Quando informado, o PTR utilizará este domínio ao invés do domínio principal. Aceita apenas letras, números, pontos e hífens.
defer_reload=1: Pula o reload automático do NSD (uso em batch — chame reload_nsd no final).

Múltiplos registros com mesmo nome+tipo

A API permite múltiplos registros com mesmo subdomain + type desde que tenham host (valor) diferente. Isso é necessário para:

NS múltiplos no apex (ex: ns1.dom. e ns2.dom.)
MX com prioridades diferentes (failover)
TXT múltiplos (DKIM + SPF + verificações de domínio)

A verificação de duplicidade compara (domain, subdomain, type, host) — só rejeita "Entry already exists" se TODOS os 4 baterem.

Exemplo 1: Registro A

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=add_subdomain" \
  -d "domain=exemplo.com" \
  -d "subdomain=mail" \
  -d "type=A" \
  -d "host=192.168.1.50" \
  -d "comment=Servidor de email"

Exemplo 2: Registro PTR com Domínio Alternativo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=add_subdomain" \
  -d "domain=exemplo.com" \
  -d "subdomain=host1" \
  -d "type=PTR" \
  -d "host=192.168.1.1" \
  -d "adicional=reverso.exemplo.net"

Neste exemplo, o PTR será criado como host1.reverso.exemplo.net apontando para 192.168.1.1, ao invés de usar o domínio principal exemplo.com.

Exemplo 3: Registro MX com Prioridade

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=add_subdomain" \
  -d "domain=exemplo.com" \
  -d "subdomain=@" \
  -d "type=MX" \
  -d "host=mail.exemplo.com." \
  -d "priority=10"

Exemplo 4: Múltiplos NS no apex (sem reload imediato)

# Cada chamada com defer_reload=1 — sem reiniciar NSD
curl -X POST "..." -d "operation=add_subdomain" -d "domain=exemplo.com" \
  -d "subdomain=@" -d "type=NS" -d "host=ns1.exemplo.com." -d "defer_reload=1"
curl -X POST "..." -d "operation=add_subdomain" -d "domain=exemplo.com" \
  -d "subdomain=@" -d "type=NS" -d "host=ns2.exemplo.com." -d "defer_reload=1"
# Reload final único
curl -X POST "..." -d "operation=reload_nsd"

5. search_subdomain - Pesquisar Subdomínio

Verifica se um subdomínio específico existe.

Parâmetros Obrigatórios

domain (ou dom): Domínio
subdomain (ou subdom): Nome do subdomínio
type (ou tipo): Tipo do registro

Parâmetros Opcionais

host: Quando informado, faz busca exata por (domain + subdomain + type + host). Útil para distinguir múltiplos registros com mesmo nome+tipo mas valores diferentes (ex: 2 NS no apex). Sem host, retorna true se EXISTE QUALQUER registro com aquele subdomain + type.

Exemplo 1: Busca por nome+tipo (qualquer valor)

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=search_subdomain" \
  -d "domain=exemplo.com" \
  -d "subdomain=www" \
  -d "type=A"

Exemplo 2: Busca exata por valor

# Verifica se ESPECIFICAMENTE @ NS ns1.exemplo.com. existe
curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=search_subdomain" \
  -d "domain=exemplo.com" \
  -d "subdomain=@" \
  -d "type=NS" \
  -d "host=ns1.exemplo.com."

Resposta

{"msg": "true"}

{"msg": "false"}

6. delete_subdomain - Deletar Subdomínio

Remove um registro DNS específico.

Parâmetros Obrigatórios

domain (ou dom): Domínio
subdomain (ou subdom): Nome do subdomínio
type (ou tipo): Tipo do registro

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=delete_subdomain" \
  -d "domain=exemplo.com" \
  -d "subdomain=teste" \
  -d "type=A"

7. delete_domain - Deletar Domínio

Remove um domínio e todos os seus registros.

Parâmetros Obrigatórios

domain (ou dom): Nome do domínio

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=delete_domain" \
  -d "domain=dominio-antigo.com"

8. reload_nsd - Recarregar NSD On-Demand

Dispara reload do servidor NSD e aguarda confirmação de processamento (até 15s). Use após operações em batch com defer_reload=1.

A resposta inclui se o reload foi confirmado e quantos milissegundos esperou.

Parâmetros

Nenhum além dos básicos (token, action=dns).

Exemplo

curl -X POST "https://seu-servidor-ravi/api.php" \
  -d "token=SEU_TOKEN" \
  -d "action=dns" \
  -d "operation=reload_nsd"

Resposta de Sucesso (reload confirmado)

{
  "msg": "ok",
  "reload_confirmed": true,
  "waited_ms": 1200
}

Resposta com Timeout

{
  "msg": "ok_reload_timeout",
  "reload_confirmed": false,
  "waited_ms": 15000
}

Quando reload_confirmed=false, o reload foi disparado mas o daemon ravi-monitor (responsável por aplicar config no NSD) demorou mais de 15s para processar. Pode acontecer se o daemon estiver carregado com outras tarefas. Mudanças DNS ainda serão aplicadas, mas com latência.

Exemplos Práticos

Script Shell

#!/bin/bash

TOKEN="seu_token_aqui"
API_URL="https://seu-servidor-ravi/api.php"
DOMAIN="exemplo.com"

# Função para adicionar domínio
add_domain() {
    local domain="$1"

    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dns" \
        -d "operation=add_domain" \
        -d "domain=$domain"
}

# Função para adicionar subdomínio
add_subdomain() {
    local domain="$1"
    local subdomain="$2"
    local type="$3"
    local host="$4"

    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dns" \
        -d "operation=add_subdomain" \
        -d "domain=$domain" \
        -d "subdomain=$subdomain" \
        -d "type=$type" \
        -d "host=$host"
}

# Listar domínios
list_domains() {
    curl -s -X POST "$API_URL" \
        -d "token=$TOKEN" \
        -d "action=dns" \
        -d "operation=authoritative"
}

# Exemplo de uso
add_domain "$DOMAIN"
add_subdomain "$DOMAIN" "www" "A" "192.168.1.100"
list_domains

Script PHP

<?php

/**
 * Adiciona domínio via API DNS
 * 
 * @param string $domain Nome do domínio
 * @return array Resposta da API
 */
function adicionarDominio($domain) {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dns',
        'operation' => 'add_domain',
        'domain' => $domain
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/**
 * Adiciona subdomínio via API DNS
 *
 * @param string $domain Domínio
 * @param string $subdomain Subdomínio
 * @param string $type Tipo do registro
 * @param string $host IP ou hostname
 * @param string $comment Comentário opcional
 * @param string $adicional Domínio alternativo para PTR (opcional)
 * @return array Resposta da API
 */
function adicionarSubdominio($domain, $subdomain, $type, $host, $comment = '', $adicional = '') {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dns',
        'operation' => 'add_subdomain',
        'domain' => $domain,
        'subdomain' => $subdomain,
        'type' => $type,
        'host' => $host,
        'comment' => $comment
    ];

    if ($adicional) {
        $data['adicional'] = $adicional;
    }

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/**
 * Lista domínios autoritativos
 * 
 * @param string $domain Domínio específico (opcional)
 * @return array Resposta da API
 */
function listarDominios($domain = '') {
    $token = 'seu_token_aqui';
    $apiUrl = 'https://seu-servidor-ravi/api.php';

    $data = [
        'token' => $token,
        'action' => 'dns',
        'operation' => 'authoritative'
    ];

    if ($domain) {
        $data['domain'] = $domain;
    }

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

/*
Uso básico:

// Adicionar domínio
$resultado = adicionarDominio('novosite.com');

// Adicionar subdomínio
$resultado = adicionarSubdominio('exemplo.com', 'www', 'A', '192.168.1.100');

// Adicionar PTR com domínio alternativo
$resultado = adicionarSubdominio('exemplo.com', 'host1', 'PTR', '192.168.1.1', '', 'reverso.exemplo.net');

// Listar todos os domínios
$dominios = listarDominios();

// Listar domínio específico
$dominio = listarDominios('exemplo.com');

// Verificar se funcionou
if ($resultado['msg'] === 'ok') {
    echo "Operação realizada com sucesso";
} else {
    echo "Erro: " . $resultado['msg'];
}
*/

?>

Códigos de Retorno

Código	Descrição
`"ok"`	Operação realizada com sucesso
`"ok_reload_timeout"`	Reload do NSD disparado mas confirmação demorou >15s (`reload_nsd`)
`"Please provide a valid domain"`	Domínio não informado
`"Domain already exists"`	Domínio já existe
`"Entry already exists"`	Registro idêntico já existe (mesmo `domain+subdomain+type+host`)
`"Domain not found"`	Domínio não encontrado
`"Subdomain not found"`	Subdomínio não encontrado
`"true"`	Subdomínio encontrado (search_subdomain)
`"false"`	Subdomínio não encontrado (search_subdomain)
`"Alternative domain cannot contain spaces or special characters"`	Domínio alternativo inválido
`"No authoritative domains found"`	Nenhum domínio autoritativo
`"No DNS log data found"`	Sem dados de estatísticas

Tipos de Registros Suportados

A: IPv4
AAAA: IPv6
CNAME: Alias
MX: Mail Exchange (use parâmetro priority)
TXT: Texto (auto-quoted + split em chunks de 255 chars no zone file conforme RFC 4408 — strings longas como DKIM funcionam direto)
PTR: Reverso (use adicional para domínio reverso customizado)
NS: Name Server (múltiplos no mesmo apex permitidos)

Reload Automático do NSD

Operações de mutação (add_*, delete_*) disparam reload síncrono do NSD por padrão. A resposta da API só retorna depois do reload completar (~1-2s).

Para batch (várias mudanças seguidas), use defer_reload=1 em todas + reload_nsd no final.
O daemon ravi-monitor (binário C, root) processa o reload em até 1-2s normalmente.

Limitações

Domínios devem ter formato válido (FQDN)
Registros idênticos (domain+subdomain+type+host) não são duplicados — retorna "Entry already exists"
Múltiplos registros com mesmo subdomain+type mas host diferente SÃO permitidos (ex: 2 NS, MX redundantes)
Verificar permissões do token (dns) antes de usar
Reload do NSD em batch mode requer chamada explícita a reload_nsd no final

Nota: Após adicionar ou remover domínios/subdomínios, o sistema automaticamente processa as alterações no DNS.

API DNS - Gerenciamento de Domínios

Visão Geral

Parâmetros Base

Parâmetro Global Opcional: defer_reload

Operações Disponíveis

1. recursive - Estatísticas do DNS Recursivo

Exemplo de Requisição

Resposta

2. authoritative - Listar Domínios Autoritativos

Parâmetros Opcionais

Exemplo 1: Todos os Domínios

Exemplo 2: Domínio Específico

Resposta

3. add_domain - Adicionar Domínio

Parâmetros Obrigatórios

Exemplo

Resposta de Sucesso

Resposta de Erro

4. add_subdomain - Adicionar Subdomínio

Parâmetros Obrigatórios

Parâmetros Opcionais

Múltiplos registros com mesmo nome+tipo

Exemplo 1: Registro A

Exemplo 2: Registro PTR com Domínio Alternativo

Exemplo 3: Registro MX com Prioridade

Exemplo 4: Múltiplos NS no apex (sem reload imediato)

5. search_subdomain - Pesquisar Subdomínio

Parâmetros Obrigatórios

Parâmetros Opcionais

Exemplo 1: Busca por nome+tipo (qualquer valor)

Exemplo 2: Busca exata por valor

Resposta

6. delete_subdomain - Deletar Subdomínio

Parâmetros Obrigatórios

Exemplo

7. delete_domain - Deletar Domínio

Parâmetros Obrigatórios

Exemplo

8. reload_nsd - Recarregar NSD On-Demand

Parâmetros

Exemplo

Resposta de Sucesso (reload confirmado)

Resposta com Timeout

Exemplos Práticos

Script Shell

Script PHP

Códigos de Retorno

Tipos de Registros Suportados

Reload Automático do NSD

Limitações

Parâmetro Global Opcional: `defer_reload`