Documentação da API PDNS
A documentação será apresentada em bash utilizando o comando curl e alguns exemplos em python v3.8+.
A API é REST e se comunica apenas via HTTPS utilizando TLSv1.2 como mínimo, embora em versões futuras seja permitido negociar somente a partir de TLSv1.3, devido às diferenças de segurança em relação às versões anteriores e à possibilidade de RTT oferecida pelo v1.3.
Versões da PDNS-API
Existem poucos endpoints na versão 2.0, 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 necessidade de utilizar a interface web.
Autenticação e Métodos
A autenticação é orientada a Resellers dentro de um ambiente multi-tenant. Devem ser especificados dois cabeçalhos para permitir a autorização:
Reseller |
Authorization |
No cabeçalho Reseller deve ser informado o crm-id ou short-name (não o nome completo) do Reseller.
No cabeçalho Authorization deve ser informada a APIKEY atribuída ao Reseller.
De acordo com a política de segurança e a capacidade de orquestração da organização que irá implementar a API, é possível realizar rollover frequente das APIKEYs.
Recomenda-se armazenar ambos os dados em variáveis de ambiente, seja em uma aplicação (por exemplo em um .env) ou globalmente em um container ou servidor, por exemplo em ~/.bashrc.
Exemplo de variáveis de ambiente no bash:
export PDNS_APIURI="https://api-server.cirion.live"
export PDNS_RESELLER="reseller01"
export PDNS_APIKEY="api-key-QueeSihuak2aegai"
Aviso
Em uma futura versão serão incorporadas APIKEYs em nível de Empresa abaixo de um Reseller, por exemplo para que uma empresa tenha autonomia para implementar um esquema de failover (por exemplo monitorar um site espelhado e alterar o IP para o mirror caso o site principal caia) sem recorrer ao provedor.
Os métodos permitidos são
GET |
POST |
PUT |
DELETE |
O método GET é utilizado para obter informações.
O método POST é utilizado para inserir um novo elemento ou modificá-lo.
O método PUT é utilizado para modificar elementos existentes.
O método DELETE é utilizado para remover elementos.
Nota
Os exemplos são apresentados majoritariamente 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 dos resolvers, os blocos aos quais se permite acesso são declarados na interface web. Sua obtenção pode ser realizada por meio da 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, seria possível gerar o mesmo resultado 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 resellers com licença de 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 é mostrado 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 reseller é obtida da seguinte maneira:
Aviso
Dependendo se a autenticação será feita com HTTP_RESELLER ou HTTP_COMPANY, em cada caso com sua respectiva APIKEY, este endpoint retorna a lista de domínios do Reseller 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 estejam suspensos. A suspensão de empresas e domínios foi introduzida na versão 2.1.
E aqui é apresentado um exemplo de resultado em JSON, 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:
Key |
Explanation |
|---|---|
domain |
nome do domínio |
type |
o 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 |
isto 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 uma 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á ativado |
deploy_dnssec |
indica se o DNSSEC deve ser ativado neste domínio |
acl |
aqui vai o nome da Access Control List declarada para permitir a transferência de zona deste domínio para outros servidores |
company |
esta é a empresa, dentro do Reseller, à qual este domínio pertence |
Obtenção do SOA de um domínio (GET, v2.0)
Esta chamada GET leva o nome do domínio na URI, do 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
}
]
As informações do SOA são muito importantes para o domínio.
Key |
Explanation |
|---|---|
mname |
Primary Master Name Server |
rname |
Responsible Person’s Email Address |
expire_ttl |
é o tempo máximo que um secundário pode ficar sem atualizar a zona a partir do primário. Após esse tempo máximo, ele deixa 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 backoff que um 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 existe uma nova versão da zona. |
serial |
Responsible Person’s Email Address |
Nota
no PDNS, o refresh_ttl muitas vezes é sobreposto pela mensagem NOTIFY, já que 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á em modo calendário, no formato YYYYMMDDHH (quatro dígitos para o ano, dois para o mês, dois para o dia, dois para a hora ou, alternativamente, dois dígitos de 00 a 99). A interface PDNS permite, no entanto, especificar para cada domínio se está em modo calendário ou em 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 para facilitar a criação de zonas em autoritativos. Ele só é necessário em alguns registros, como MX.
Nota
O valor de rr_id é único e permite tanto modificar quanto remover um registro.
Remover um Resource Record por ID (DELETE)
É possível remover um resource 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 ele não existir ou não fizer parte do domínio que estamos enviando 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 correspondente.
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
Aplicam-se as restrições explicadas no manual do PDNS para CNAMEs, como a não permissão de sobreposição de CNAMEs com outros registros e, portanto, a proibição de CNAME no APEX da zona, pois ali já se encontra o registro SOA.
Nota
o serial SOA da zona é incrementado automaticamente em 1 (um)
Nota
Uma zona reversa admite apenas registros NS e PTR, além do SOA que é criado junto com a zona.
Exemplo de JSON para SRV:
curl -X POST "${PDNS_APIURI}/api/v1/domain_rr/assetcrypt.com" \
-H "Authorization: ${PDNS_APIKEY}" \
-H "Reseller: ${PDNS_RESELLER}" \
-d '{
"rr_ttl": 3600,
"rr_name": "_sipfederationtls._tcp",
"rr_type": "SRV",
"rr_prio": 100,
"rr_weight": 1,
"rr_port": 5061,
"rr_value": "sipfed.online.lync.com"
}'
Aviso
No caso de registros SRV, são necessários os seguintes parâmetros adicionais:
rr_port(padrão 443)rr_weightrr_prio(similar ao MX)
O valor rr_value representa o srv host. O valor final do registro SRV é obtido concatenando: priority weight port target.
Exemplo de JSON para CAA:
curl -X POST "${PDNS_APIURI}/api/v1/domain_rr/assetcrypt.com" \
-H "Authorization: ${PDNS_APIKEY}" \
-H "Reseller: ${PDNS_RESELLER}" \
-d '{
"rr_ttl": 3600,
"rr_name": "",
"rr_type": "CAA",
"rr_value": "letsencrypt.org",
"rr_flag": 128,
"rr_tag": "issue"
}'
Aviso
No caso de registros CAA, podem ser necessários os seguintes parâmetros adicionais:
rr_flag(0 ou 128)rr_tag(issue,issuewildouiodef)
O domínio da autoridade certificadora é obtido a partir do campo rr_value (obrigatório).
Aviso
No caso de registros CAA, eventualmente serão necessários os seguintes parâmetros adicionais: rr_flag (0 ou 128), rr_tag (padrão «issue», também pode ser «iodef» ou «issuewild»). O host (por exemplo «letsencrypt.org») é obtido do rr_value (obrigatório).
Modificar um Resource Record por ID (PUT)
A partir do ID de um RR, é possível modificar seu TTL, seu valor ou também 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
Ao dispor do ID, só é necessário enviar 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 Reseller (GET)
As ACLs ou Access Control Lists permitem definir permissões de transferência para domínios que estão autorizados a ser transferidos para outros servidores. Ou seja, domínios cujo conteúdo completo pode ser copiado.
Cada vez que se permite a transferência de um domínio, devem ser especificados IPv4 ou IPv6 de forma individual ou em bloco, ou uma chave criptográfica TSIG que permita a quem a possua obter uma cópia do 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 à lista de ACLs de um reseller:
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 ter 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 em particular, como sua apikey e se ela está suspensa ou não.
{
"crm_id": "vlans",
"name": "Vlans",
"apikey": "ru34wbSYPb",
"suspended": false
}
Nota
Se desejar obter uma lista de empresas gerenciadas pelo Reseller, deve utilizar a chamada ao método companies.
Aviso
Se o crm_id enviado na URL não corresponder a nenhuma Empresa, a chamada retorna um HTTP 400 junto com um JSON: {«msg»:»crmid01 does not exist»}
Modificação de dados de uma Empresa (PUT)
Deve-se enviar na URL um crm_id da empresa a ser modificada, e os campos que se deseja modificar, incluindo o próprio crm_id (somente os valores presentes no JSON serão modificados), por exemplo.
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 efetivas para todos os domínios da Empresa.
Nota
Se um domínio estiver no estado suspended, significa que os servidores autoritativos do Reseller não irão anunciá-lo/publicá-lo.
Aviso
Caso o crm_id seja alterado, será verificado se ele é válido (alfanumérico, apenas “-“ e “_” como caracteres especiais permitidos, e será convertido para minúsculas por se tratar de 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)
Deve-se enviar um crm_id com as restrições definidas anteriormente, um name ou nome, e uma apikey. O estado inicial de suspended é False, ou seja, a empresa está ativa para que todos os domínios associados a ela também estejam ativos por padrão à medida que forem criados.
O endpoint verifica se o crm_id não existe previamente e se foram fornecidos name e apikey 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" }'
Caso o crm_id já exista, a API retorna um erro 400 e uma mensagem {«msg»:»Company nuevaempresa1 already exists»}
Remoção de uma Empresa (DELETE)
Deve-se enviar um crm_id com as restrições definidas anteriormente e a apikey da empresa por segurança, para reafirmar a solicitação.
O endpoint verifica se o crm_id existe; caso contrário, retorna um erro 400 com a mensagem {«msg»:»Company empresaxyz does not exist»}.
Aviso
Este endpoint remove todos os domínios pertencentes à empresa.
curl -X DELETE ${PDNS_APIURI}/api/v1/company/empresaxyz -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "apikey": "company_apikey001" }'
Nota
Recomenda-se suspender uma empresa em caso de desativação e, somente após algum tempo, proceder a uma limpeza por meio da remoção.
Criação de uma zona master (POST)
Para criar uma zona master, deve-se especificar a qual empresa ela 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 se tratar de uma zona nova ou interna. Além disso, deverão 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 0 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 informando que falta um campo. Também realiza verificações de consistência, por exemplo em relação ao mname ou Master DNS Name, que é colocado automaticamente como registro NS ao criar a zona, e também cria o registro SOA com os dados fornecidos.
Caso a zona já exista dentro do Reseller, retornará um erro 400 com uma mensagem de Zona duplicada.
A zona é criada com o parâmetro suspended em False, ou seja, a zona é ativada imediatamente.
Alteração de 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 inclusive 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
Só é necessário fornecer os valores que serão modificados
Zona master reversa
Em relação à criação de zonas, valem as seguintes observações:
Aviso
caso a zona termine em in-addr.arpa ou ip6.arpa, a zona será considerada reversa em vez de direta. Esta metadata não pode ser alterada.
Nota
Diferentemente da interface web, onde se utiliza a notação direta de uma /24, por exemplo 123.221.24.0/24 para indicar 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, por exemplo, 2803:bc00::9A; o valor expandido é 2803:bc00:0000:0000:0000:0000:0000:009a. Caso se deseje 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 ela pertence (crm_id), um fqdn ou Fully Qualified Domain Name, e os master-ips. O nome não precisa ser reconhecido na Internet, pois pode se tratar de uma zona nova ou interna. Os master-ips podem ser um ou dois; são os endereços IP de onde o autoritativo do Reseller 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 informando que falta um campo.
Nota
Apenas masterip1 é obrigatório
Caso a zona já exista dentro do Reseller, retornará um erro 400 com uma mensagem de Zona duplicada.
A zona é criada com o parâmetro suspended em False, ou seja, a zona é ativada imediatamente.
Aviso
caso a zona termine em in-addr.arpa ou ip6.arpa, a zona será considerada reversa em vez de direta. Esta metadata não pode ser alterada.
Suspensão e Reativação de uma zona (PUT)
Uma zona pode ser reativada e suspensa sucessivamente utilizando chamadas PUT aos seguintes endpoints, por exemplo:
curl -X PUT ${PDNS_APIURI}/api/v1/suspend_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{"crm_id": "mycompany"}'
curl -X PUT ${PDNS_APIURI}/api/v1/resume_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{"crm_id": "mycompany"}'
Nota
Suspender uma zona significa que ela não será publicada nos DNSs autoritativos correspondentes ao Reseller onde está a Empresa à qual a zona pertence. No entanto, podem ser feitas modificações via Web ou API nos registros da zona, pois eles permanecem disponíveis.
Remoção de uma zona (DELETE)
Para remover uma zona, deve-se simplesmente utilizar o método DELETE, com o qual também serão removidos todos os seus Resource Records, incluindo o SOA. 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 removida a zona, não resta nenhum rastro 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)
Exemplo de key em formato bind9, gerada com /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 de 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 key com o nome keyname usando o algoritmo hmac-256.
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=="
}
Remoção de uma slave TSIG (DELETE)
A remoção só é possível desde que não haja zonas slave que precisem dela.
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.
Adicionalmente, pode-se adicionar TSIG ou uma chave criptográfica, caso seja exigida pelo servidor que disponibiliza a zona, especificando o nome da key.
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 expõe essa zona através de vários IPs e uma chave TSIG, devemos criar a chave primeiro com createkey e depois adicionar seu nome nesta chamada a secure_slave_zone, de modo a associar a key aos IPs masters (dos quais, escolhidos aleatoriamente, será feita a tentativa de trazer a zona para o nosso primário do Reseller correspondente).