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

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,
          "value": "www",
          "type": "A",
          "host": "192.168.1.100"
        },
        {
          "id": 2,
          "value": "ns1",
          "type": "A",
          "host": "192.168.1.10"
        }
      ]
    }
  ]
}

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

Exemplo

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"

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

Exemplo

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"

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"

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
 * @return array Resposta da API
 */
function adicionarSubdominio($domain, $subdomain, $type, $host, $comment = '') {
    $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
    ];

    $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');

// 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
`"Please provide a valid domain"`	Domínio não informado
`"Domain already exists"`	Domínio já existe
`"Entry already exists"`	Registro já existe
`"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)
`"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
TXT: Texto
PTR: Reverso
NS: Name Server

Limitações

Domínios devem ter formato válido
Registros duplicados não são permitidos
Alterações requerem reinicialização do serviço DNS
Verificar permissões do token antes de usar

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