Documentação da API PDNS
A documentação será elaborada em bash com o comando curl e alguns exemplos em python v3.8+.
A API é REST e se comunica apenas via HTTPS com TLSv1.2 no mínimo, embora em versões futuras só será permitido negociar a partir do TLSv1.3, devido à lacuna de segurança nas versões anteriores e à possibilidade de RTT oferecida pelo v1.3.
Versões da PDNS-API
Existem muito poucos endpoints na versão 2.0, e são destinados a intervir dinamicamente na configuração dos resolvers e autoritativos.
Somente a partir da versão 2.1 são fornecidos mais endpoints, permitindo construir um CRM ou uma aplicação sem a necessidade de utilizar a interface web.
Autenticação e Métodos
A autenticação é direcionada para Revendedores dentro da multi-tenência. Devem ser especificados dois cabeçalhos para permitir a autorização:
Revendedor |
Autorização |
No cabeçalho Reseller vai o crm-id ou short-name (não o nome longo completo) do Revendedor.
No cabeçalho Authorization vai a APIKEY atribuída ao Revendedor.
De acordo com a política de segurança e a capacidade de orquestração da organização que irá implementar a API, pode realizar o rollover frequente de suas APIKEYs.
Recomenda-se armazenar ambos os dados em variáveis de ambiente, seja próprias de uma aplicação (por exemplo, em um .env) ou globais de um container ou servidor, por exemplo, em ~/.bashrc.
Por exemplo, variáveis de ambiente do bash:
export PDNS_APIURI="https://api-server.cirion.live"
export PDNS_RESELLER="reseller01"
export PDNS_APIKEY="api-key-QueeSihuak2aegai"
Aviso
Em uma versão futura, serão incorporadas APIKEYs ao nível de Empresa abaixo de um Revendedor, por exemplo, para que uma empresa tenha a autonomia de implementar um esquema de failover (por exemplo, monitorar um site espelhado e mudar o IP para o espelho se o site principal cair) sem recorrer ao seu provedor.
Os métodos permitidos são
GET |
POST |
PUT |
DELETE |
O método GET é para obter uma informação.
O método POST é para inserir um novo elemento ou modificá-lo.
O método PUT é para modificar elementos existentes.
O método DELETE é para excluir elementos.
Nota
Os exemplos são apresentados principalmente em um ambiente bash hipotético com as variáveis de ambiente descritas.
Endpoints v2.0
A seguir, são apresentados os métodos v2.0 destinados a interagir com a configuração do bind9 e, em geral, obter informações sobre os dados inseridos na interface web.
Obtenção de blocos permitidos para resolvers (GET)
No caso de resolvers, os blocos permitidos são declarados na interface web. A obtenção pode ser feita via API:
curl -X GET ${PDNS_APIURI}/api/v1/api_trusted_blocks -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}
Isso retorna um JSON com os blocos declarados na interface web:
[
{
"cidr_block": "184.103.220.0/24"
},
{
"cidr_block": "181.122.241.0/24"
},
{
"cidr_block": "200.187.43.157"
}
]
Em python3, o mesmo resultado pode ser gerado com o seguinte código:
import requests
import sys
import os
reseller=os.environ['PDNS_RESELLER']
apikey=os.environ['PDNS_APIKEY']
apiuri=os.environ['PDNS_APIURI']
try:
response = requests.get( f"{apiuri}/api/v1/api_trusted_blocks",
headers={
'Accept':'application/json',
'Content-type': 'application/json',
"Authorization":f"{apikey}",
"Reseller":f"{reseller}"
}
)
except Exception as e:
print( f"ERROR: al enviar el request {str(e)}" )
sys.exit(-1)
print(response.json())
Obtenção de zonas RPZ ativadas (GET, v2.0)
Para os revendedores com licença Feed RPZ, este endpoint permite obter as Response Policy Zones ativadas.
curl -X GET ${PDNS_APIURI}/api/v1/api_rpz_zones -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}
A seguir é apresentado o formato de um resultado hipotético:
[
{
"zone_name": "planisys.phishing"
},
{
"zone_name": "planisys.spam"
},
{
"zone_name": "planisys.malware"
},
{
"zone_name": "coinblocker.srv"
},
{
"zone_name": "porn.host.srv"
},
{
"zone_name": "torblock.srv"
},
{
"zone_name": "drop.ip.dtq"
},
{
"zone_name": "urlhaus.zone"
}
]
Obtenção da lista de domínios (GET, v2.0)
A lista completa de domínios de um revendedor pode ser obtida da seguinte maneira:
Aviso
Dependendo se a autenticação será com HTTP_RESELLER ou HTTP_COMPANY, cada um com sua respectiva APIKEY, este endpoint retorna a lista de domínios do Revendedor ou da Empresa.
curl -X GET ${PDNS_APIURI}/api/v1/domain_list -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
Aviso
Este endpoint retorna apenas domínios ativos, ou seja, domínios que não foram suspensos. A suspensão de empresas e domínios foi introduzida na versão 2.1.
Aqui está um exemplo de JSON de resultado, com dois domínios:
[
{
"domain": "assetcrypt.com",
"type": "master",
"master1": "",
"master2": "",
"soa_serial": 2024032003,
"allow_axfr": false,
"tsig": "",
"dnssec": true,
"deploy_dnssec": false,
"acl": "none",
"company": "1-planisys"
},
{
"domain": "psys.ar",
"type": "master",
"master1": "",
"master2": "",
"soa_serial": 2024021305,
"allow_axfr": false,
"tsig": "",
"dnssec": true,
"deploy_dnssec": false,
"acl": "none",
"company": "1-planisys"
}
]
Os dados recebidos no JSON de cada domínio são:
Chave |
Explicação |
|---|---|
domínio |
nome do domínio |
tipo |
tipo é master ou slave |
master1 |
caso seja slave, o primeiro master |
master2 |
caso seja slave, o segundo master |
soa_serial |
o serial do registro SOA |
allow_axfr |
isso pode ser true ou false. Se for true, deve existir uma ACL para especificar quem está autorizado a copiar o domínio via AXFR. |
tsig |
esta é uma chave TSIG para proteger adicionalmente domínios que permitem transferência de zona ou AXFR para outros servidores. |
dnssec |
indica se o DNSSEC está ativado, ou seja, se já existem registros assinados e se o rollover está ativo. |
deploy_dnssec |
indica se o DNSSEC deve ser ativado neste domínio. |
acl |
aqui vai o nome da lista de controle de acesso (ACL) declarada para permitir a transferência de zona deste domínio para outros servidores. |
company |
esta é a empresa, dentro do Revendedor, à qual este domínio pertence |
Obtenção do SOA de um domínio (GET, v2.0)
Esta chamada GET inclui o nome do domínio na URI, da qual se deseja obter um JSON com os dados do SOA do domínio assetcrypt.com:
curl -X GET ${PDNS_APIURI}/api/v1/get_soa/assetcrypt.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
O resultado é um JSON com os dados do registro SOA (Start of Authority)
[
{
"mname": "globaldns1.planisys.net.",
"rname": "hostmaster.planisys.com",
"expire_ttl": 604800,
"minimum_ttl": 3600,
"retry_ttl": 3600,
"refresh_ttl": 10800,
"serial": 2024032003
}
]
A informação do SOA é muito importante para o domínio.
Chave |
Explicação |
|---|---|
mname |
Servidor Master Primário |
rname |
Endereço de E-mail da Pessoa Responsável |
expire_ttl |
é o tempo máximo que um servidor secundário pode ficar sem atualizar a zona a partir do primário. Após esse tempo, ele para de responder pela zona. |
minimum_ttl |
Especifica o TTL mínimo de cada registro da zona, para quando o TTL não é especificado no registro. É o tempo de cache dos resolvers para cada RR (Resource Record). |
retry_ttl |
É o tempo de espera que um servidor secundário deve aguardar antes de tentar novamente transferir a zona de um master, em caso de falha na transferência. |
refresh_ttl |
É a frequência com que o secundário perguntará ao primário se há uma nova versão da zona. |
serial |
Endereço de E-mail da Pessoa Responsável |
Nota
No PDNS, o refresh_ttl muitas vezes é substituído pela mensagem NOTIFY, pois o PDNS gera a lista de zonas com uma diretiva para notificar os IPs dos secundários sempre que houver uma alteração.
Aviso
O serial geralmente está no modo calendário, sendo YYYYMMDDHH (quatro dígitos para oano, dois para o mês, dois para o dia e dois para a hora, ou alternativamente dois dígitosde 00 a 99). A interface PDNS permite, no entanto, especificar para cada domínio se estáno modo calendário ou no modo serial puro, que é um número crescente.
Obter Resource Records de um domínio (GET)
Exemplo: obter um JSON com os Resource Records (registros), exceto o SOA, que é obtido separadamente, do domínio assetcrypt.com.
curl -X GET ${PDNS_APIURI}/api/v1/domain_rr_list/assetcrypt.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"|jq
O resultado é um JSON representando uma lista de RRs:
[
{
"rr_id": 43214,
"rr_ttl": 3600,
"rr_name": "*.subdom",
"rr_type": "CNAME",
"rr_prio": "0",
"rr_value": "www.planisys.net."
},
{
"rr_id": 37245,
"rr_ttl": 3600,
"rr_name": "@",
"rr_type": "A",
"rr_prio": "0",
"rr_value": "38.83.73.10"
},
{
"rr_id": 112,
"rr_ttl": 3600,
"rr_name": "@",
"rr_type": "AAAA",
"rr_prio": "0",
"rr_value": "2803:bc00::98"
},
{
"rr_id": 917,
"rr_ttl": 3600,
"rr_name": "@",
"rr_type": "NS",
"rr_prio": "0",
"rr_value": "globaldns1.planisys.net"
},
{
"rr_id": 875,
"rr_ttl": 3600,
"rr_name": "@",
"rr_type": "NS",
"rr_prio": "0",
"rr_value": "globaldns2.planisys.net"
},
{
"rr_id": 34103,
"rr_ttl": 3600,
"rr_name": "@",
"rr_type": "MX",
"rr_prio": "10",
"rr_value": "avas-mx-corpmail7-1.planisys.net."
},
{
"rr_id": 229,
"rr_ttl": 3600,
"rr_name": "tipo1conpunto",
"rr_type": "CNAME",
"rr_prio": "0",
"rr_value": "www.assetcrypt.com."
},
{
"rr_id": 136,
"rr_ttl": 3600,
"rr_name": "tipo1sinpunto",
"rr_type": "CNAME",
"rr_prio": "0",
"rr_value": "www"
},
{
"rr_id": 154,
"rr_ttl": 3600,
"rr_name": "www",
"rr_type": "CNAME",
"rr_prio": "0",
"rr_value": "www.planisys.net."
}
]
Nota
O valor de rr_prio é numérico, mas é retornado como string parafacilitar a criação de zonas em servidores autoritativos. Só é necessário em alguns registros, como MX.
Nota
O valor de rr_id é único e permite tanto modificar quanto excluir um registro.
Excluir um Resource Record por ID (DELETE)
É possível excluir um recurso por ID.
curl -X DELETE ${PDNS_APIURI}/api/v1/domain_rr/assetcrypt.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "rr_id": 176 }'
Se não existir ou não fizer parte do domínio enviado na URI, retorna um erro 400.
Nota
o serial SOA da zona é incrementado automaticamente em 1 (um).
Criar um Resource Record (POST)
A criação de um RR dentro de uma zona retorna o ID do mesmo.
Neste caso, criamos um registro dentro da zona assetcrypt.com.
curl -X POST ${PDNS_APIURI}/api/v1/domain_rr/assetcrypt.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "rr_ttl": 360, "rr_name": "www", "rr_type": "A", "rr_prio": 0, "rr_value": "123.223.111.222" }'
Aviso
As restrições explicadas no manual do PDNS para CNAMEs se aplicam, como a proibição da sobreposição de CNAMEs com outros registros e, portanto, a proibição de CNAME no APEX da zona, já que lá já está o registro SOA.
Nota
o serial SOA da zona é incrementado automaticamente em 1 (um).
Nota
Uma zona reversa só permite registros NS e PTR, além do SOA, que é criado junto com a zona.
Modificar um Resource Record por ID (PUT)
Com o ID de um RR, é possível modificar seu TTL, seu valor ou até mesmo o tipo:
curl -X PUT ${PDNS_APIURI}/api/v1/domain_rr/assetcrypt.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "rr_id": 176, "rr_ttl": 3600 }'
Nota
Com o ID disponível, é necessário enviar apenas os campos que serão modificados. Ou seja, não é necessário repetir tudo novamente.
Nota
o serial SOA da zona é incrementado automaticamente em 1 (um).
Obter ACLs de um Revendedor (GET)
ACLs ou Access Control Lists permitem definir permissões de transferência para domínios que podem ser transferidos para outros servidores. Ou seja, domínios cujo conteúdo completo pode ser copiado.
Sempre que um domínio puder ser transferido, deve-se especificar IPv4 ou IPv6 individualmente ou em bloco, ou uma chave criptográfica TSIG que permita a quem a possui copiar o domínio, independentemente do IP de origem.
Uma ACL possui um nome e é uma lista de possíveis blocos ou IPs individuais (ou seja, /32) IPv4 e/ou IPv6, e possivelmente uma chave TSIG.
Por exemplo, uma chamada para a lista de ACLs de um revendedor:
curl -X GET ${PDNS_APIURI}/api/v1/get_acls -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"|jq
Um exemplo do que este endpoint pode retornar: duas ACLs, uma chamada ACL1 e outra 1-planisys_globaldns-pdns.
[
{
"acl_name": "1-planisys_globaldns-pdns",
"items": [
{
"component": "131.108.40.71",
"comment": "powerdns web interface",
"type": "ipv4addr"
},
{
"component": "143.42.183.85",
"comment": "nj-dns",
"type": "ipv4addr"
},
{
"component": "64.64.107.50",
"comment": "lw-dns",
"type": "ipv4addr"
},
{
"component": "63.251.107.116",
"comment": "inap-dns",
"type": "ipv4addr"
},
{
"component": "2600:3c03::f03c:93ff:fe99:49bd",
"comment": "nj-dns",
"type": "ipv6addr"
},
{
"component": "185.180.8.10",
"comment": "planisys-miami",
"type": "ipv4addr"
},
{
"component": "179.63.248.233",
"comment": "planisys-miami",
"type": "ipv4addr"
},
{
"component": "179.63.248.234",
"comment": "planisys-miami",
"type": "ipv4addr"
},
{
"component": "179.63.249.133",
"comment": "planisys-miami",
"type": "ipv4addr"
},
{
"component": "179.63.249.134",
"comment": "planisys-miami",
"type": "ipv4addr"
}
]
},
{
"acl_name": "ACL1",
"items": [
{
"component": "131.108.40.71",
"comment": "dns1",
"type": "ipv4addr"
}
]
},
]
Endpoints v2.1
Estes são os endpoints disponíveis na versão 2.1 em fevereiro de 2024.
Obtenção da lista de Empresas (GET)
curl -X GET ${PDNS_APIURI}/api/v1/companies -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
[
{
"crm_id": "vlans",
"name": "Vlans",
"apikey": "ru34wbSYPb",
"suspended": false
},
{
"crm_id": "munibelleville",
"name": "Municipalidad",
"apikey": "8789y3kv0D",
"suspended": false
}
]
Obtenção de dados de uma Empresa (GET)
Esta chamada GET deve incluir um parâmetro no JSON de entrada para obter dados de uma empresa chamada «vlans».
curl -X GET ${PDNS_APIURI}/api/v1/company/vlans -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
O resultado é um JSON com dados operacionais dessa empresa específica, como sua apikey e se está suspensa ou não.
{
"crm_id": "vlans",
"name": "Vlans",
"apikey": "ru34wbSYPb",
"suspended": false
}
Nota
Se você quiser obter uma lista de empresas gerenciadas pelo Revendedor, use a chamada para o método companies.
Aviso
Se o crm_id enviado na URL não corresponder a nenhuma Empresa, a chamada retornará um HTTP 400 com um JSON: {«msg»:»crmid01 does not exist»}.
Modificação de dados de uma Empresa (PUT)
Se debe enviar en la URL un crm_id de empresa a modificar, y aquellos campos que se quiera modificar incluyendo el propio crm_id (solo se modifican aquellos valores que figuran en el JSON), p.ej.
curl -X PUT ${PDNS_APIURI}/api/v1/company/vlans -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{"apikey": "newapikey001", "suspended": true}'
Aviso
Caso o valor de suspended seja modificado, as alterações serão aplicadas a todos os domínios da Empresa.
Nota
Se um domínio estiver no estado suspended, significa que os servidores autoritativos do Revendedor não o anunciarão/publicarão.
Aviso
Caso o crm_id seja alterado, será verificado se é válido (alfanumérico, com apenas “-“ e “_” como caracteres especiais permitidos, e será convertido para minúsculas por ser uma chave de busca).
Aviso
Caso a apikey seja alterada, todos os espaços, “,” e “;” serão removidos, pois não são permitidos como parte de uma chave API.
Criação de uma Empresa (POST)
Um crm_id deve ser enviado com as restrições definidas anteriormente,juntamente com um name (nome) e uma apikey. O estado inicial de `suspended`é False, ou seja, a empresa está ativa para que todos os domínios associadosa ela também estejam ativos por padrão à medida que são criados.
O endpoint verifica se o crm_id não existe previamente e se o nome e a apikey são fornecidos como parâmetros obrigatórios.
curl -X POST ${PDNS_APIURI}/api/v1/company/nuevaempresa1 -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "name":"Nueva Empresa1", "apikey": "newapikey001" }'
Se o crm_id já existir, a API retornará um erro 400 com a mensagem {«msg»:»Company nuevaempresa1 already exists»}.
Exclusão de uma Empresa (DELETE)
Deve-se enviar um crm_id com as restrições definidas anteriormente, a apikey da empresa por segurança, para confirmar a solicitação.
O endpoint verifica se o crm_id existe; caso contrário, retorna um erro 400 com uma mensagem {«msg»:»Company empresaxyz does not exist»}.
Aviso
Este endpoint exclui todos os domínios que pertencem à empresa.
curl -X DELETE ${PDNS_APIURI}/api/v1/company/empresaxyz -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "apikey": "company_apikey001" }'
Criação de uma zona master (POST)
Para criar uma zona master, deve-se especificar a qual empresa pertence (crm_id) e um fqdn ou Fully Qualified Domain Name (este último na URI). O nome não precisa ser reconhecido na Internet, pois pode ser uma zona nova ou uma zona interna. Além disso, devem ser fornecidos dados para o registro SOA.
O tipo de serial SOA pode ser numeric ou calendar (neste último caso é YYYYMMDDSS, sendo SS um valor de 00 a 99). No caso de calendar, a quantidade de alterações é limitada a 100 por dia.
Exemplo:
curl -X POST ${PDNS_APIURI}/api/v1/domain' -H 'Authorization: ${PDNS_APIKEY}' -H 'Reseller: ${PDNS_RESELLER}' -H 'Content-Type: application/json' -d '{"domain": "test2.com", "crm_id": "empresa2", "mname": "globaldns1.planisys.net", "rname": "hostmaster.planisys.com", "expire_ttl": 604800, "minimum_ttl": 3600, "retry_ttl": 3600, "refresh_ttl": 10800, "serial": 2024096000, "serial_type": "calendar"}'
Se faltar algum dos dados, o endpoint retorna um erro 400 indicando que falta um campo. Também realiza verificações de consistência, por exemplo, em relação ao mname ou Master DNS Name, que é inserido como registro NS automaticamente ao criar a zona, e também cria o registro SOA com os » «dados fornecidos.
Se a zona já existir dentro do Revendedor, retornará um erro 400 com a mensagem Zona duplicada.
A zona é criada com o parâmetro suspended em False, ou seja, a zona é ativada imediatamente.
Alteração do SOA ou empresa de uma zona (PUT)
Este é um caso de alteração de metadados de uma zona; basta fornecer novos valores, seja para o SOA ou para a empresa, ou até mesmo alterar o serial_type. Também serve para incrementar artificialmente o SOA de uma zona:
curl -X PUT ${PDNS_APIURI}/api/v1/zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "crm_id":"empresa2", "mname": "globaldns1.planisys.net", "rname": "hostmaster.planisys.com", "expire_ttl": 604800, "minimum_ttl": 3600, "retry_ttl": 3600, "refresh_ttl": 10800, "serial": 2200000001, "serial_type": "numeric" }'
Nota
É necessário fornecer apenas os valores que serão modificados
Zona master reversa
Em relação à criação de zonas, aplicam-se as seguintes observações:
Aviso
se a zona terminar com in-addr.arpa ou ip6.arpa, ela será considerada reversa em vez de direta. Este metadado não pode ser alterado.
Nota
Diferentemente da interface web, onde se utiliza a notação direta de uma /24, por exemplo, 123.221.24.0/24 para denotar a criação de uma zona reversa, na API utilizamos 24.221.123.in-addr.arpa diretamente como nome da zona. Atualmente, o PDNS suporta apenas zonas /24 para registros PTR.
Nota
Por exemplo, uma zona IPv6 0.0.0.0.0.0.c.b.3.0.8.2.ip6.arpa representa uma /40, com valores como 2803:bc00::9A, cujo valor expandido é 2803:bc00:0000:0000:0000:0000:0000:009a. No caso de querer representar a zona 2803:bc00:0000::/64, o nome da zona é mais longo 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.c.b.3.0.8.2.ip6.arpa
Criação de uma zona slave (POST)
Para criar uma zona slave, deve-se especificar a qual empresa pertence (crm_id), um fqdn ou Fully Qualified Domain Name, e as master-ips. O nome não precisa ser reconhecido na Internet, pois pode ser uma zona nova ou uma zona interna. As master-ips podem ser um ou dois endereços IP de onde o autoritativo do Revendedor tentará transferir a zona.
Aviso
esta versão não suporta chaves TSIG; veja secure_slave_zone para criar uma zona slave protegida com chave TSIG
Exemplo:
curl -X POST ${PDNS_APIURI}/api/v1/slave_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "masterip1": "192.168.33.44", "masterip2": "192.168.44.55" }'
Se faltar algum dos dados, o endpoint retorna um erro 400 indicando que falta um campo.
Nota
Apenas masterip1 é obrigatório
Se a zona já existir dentro do Revendedor, retornará um erro 400 com a mensagem Zona duplicada.
A zona é criada com o parâmetro suspended em False, ou seja, a zona é ativada imediatamente.
Aviso
se a zona terminar com in-addr.arpa ou ip6.arpa, ela será considerada reversa em vez de direta. Este metadado não pode ser alterado.
Suspensão e Reativação de uma zona (PUT)
Uma zona pode ser suspensa e reativada sucessivamente utilizando chamadas PUT nos seguintes endpoints, por exemplo:
curl -X PUT ${PDNS_APIURI}/api/v1/suspend_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
curl -X PUT ${PDNS_APIURI}/api/v1/resume_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
Nota
Suspender uma zona significa que ela não é publicada nos DNS autoritativos correspondentes ao Revendedor, onde se encontra a Empresa à qual a zona pertence. No entanto, podem ser realizadas modificações via Web ou API nos registros da zona, já que eles estão disponíveis.
Exclusão de uma zona (DELETE)
Para excluir uma zona, basta utilizar o método DELETE, com o qual todos os seus Resource Records, incluindo o SOA, também serão excluídos. A zona deixará de ser publicada e seus registros não estarão mais disponíveis.
Exemplo:
curl -X DELETE ${PDNS_APIURI}/api/v1/domain -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{"domain": "test.com", "crm_id": "test1"}'
Aviso
Uma vez excluída a zona, não resta nenhum vestígio dela.
Endpoints v2.2
Estes são os endpoints disponíveis na versão 2.2, prevista para agosto de 2024.
Criação de uma slave TSIG (POST)
Ejemplo de key en formato bind9, generada con /usr/sbin/tsig-keygen hola1
key "hola1" {
algorithm hmac-sha256;
secret "LvzAji80xCrq7eoD5YODSDjD0LLJLiX2nWPGSA11q1w=";
};
O endpoint para criar uma chave TSIG e publicá-la no bind9 precisa de um nome e um algoritmo. O algoritmo deve ser um dos seguintes:
hmac-md5 |
hmac-sha1 |
hmac-sha224 |
hmac-sha256 |
hmac-sha384 |
hmac-sha512 |
Este exemplo cria uma chave com o nome keyname usando o algoritmo hmac-sha256.
curl -X POST ${PDNS_APIURI}/api/v1/createkey/newkey -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "algorithm": "hmac-sha512" }'
A chamada retorna a chave em base 64
{
"algorithm": "hmac-sha512",
"keyname": "newkey",
"secret": "STe13VSVnkXdCXoe/ibjpSxzviqnGqb20VJhkDEc54cmNP3z3/s+qURW1feeYylwWa6L0hdTyHMBxivK2x2zOQ=="
}
Exclusão de uma slave TSIG (DELETE)
A exclusão só é possível desde que não haja zonas slave que a necessitem.
curl -X DELETE ${PDNS_APIURI}/api/v1/createkey/newkey -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
Criação de uma zona slave segura (POST)
Diferentemente do endpoint slave_zone, este endpoint secure_slave_zone permite declarar uma lista de IPs master (não limitada a dois, como no caso de slave_zone) e com uma chave adicional TSIG.
Além disso, pode-se adicionar uma TSIG ou chave criptográfica, se esta for requerida pelo servidor que disponibiliza a zona, especificando o nome da chave.
curl -X POST ${PDNS_APIURI}/api/v1/secure_slave_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "masters": [ "192.168.33.44", "192.168.44.55", "192.168.55.66"], "keyname": "newkey1" }'
Dessa forma, se o administrador de uma zona disponibiliza essa zona por meio de várias IPs e uma chave TSIG, devemos primeiro criar a chave com createkey e, em seguida, adicionar seu nome nesta chamada para secure_slave_zone para associar a chave às IPs master (de onde, escolhidas aleatoriamente, tentaremos trazer a zona para o nosso primário do Revendedor correspondente).