PDNS API Documentation
The documentation will be provided in bash using the curl command, along with some examples in python v3.8+.
The API is REST and communicates only via HTTPS using TLSv1.2 as a minimum, although future versions will only allow negotiation starting from TLSv1.3 due to the security gap in previous versions and the RTT improvements offered by TLSv1.3.
PDNS-API Versions
There are very few endpoints in version 2.0, and they are intended to dynamically interact with the configuration of resolvers and authoritative servers.
Starting from version 2.1, additional endpoints are provided, making it possible to build a CRM or an application without needing to use the web interface at all.
Authentication and Methods
Authentication is designed for Resellers within a multi-tenant environment. Two headers must be specified to allow authorization:
Reseller |
Authorization |
The Reseller header must contain the Reseller crm-id or short-name (not the full long name).
The Authorization header must contain the APIKEY assigned to the Reseller.
According to the organization’s security policy and orchestration capabilities when implementing the API, APIKEY rollover can be performed frequently.
It is recommended to store both values in environment variables, either application-specific (e.g. in a .env file) or globally within a container or server environment, for example in ~/.bashrc.
For example, bash environment variables:
export PDNS_APIURI="https://api-server.cirion.live"
export PDNS_RESELLER="reseller01"
export PDNS_APIKEY="api-key-QueeSihuak2aegai"
Warning
In a future version, APIKEYs at the Company level under a Reseller will be introduced, allowing a company to autonomously implement failover schemes (e.g. monitoring a mirrored site and switching the IP to the mirror if the main site fails) without relying on its provider.
The allowed methods are
GET |
POST |
PUT |
DELETE |
The GET method is used to retrieve information.
The POST method is used to create or modify an element.
The PUT method is used to modify existing elements.
The DELETE method is used to remove elements.
Note
The examples are mostly shown in a hypothetical bash environment using the described environment variables.
Endpoints v2.0
The following are the v2.0 methods intended to interact with the bind9 configuration, and more generally to retrieve information about the data entered through the web interface.
Obtención de bloques permitidos para resolvers (GET)
En el caso de resolvers, los bloques a los que permite acceder se declaran en la interfaz web. Su obtención su puede realizar mediante API:
curl -X GET ${PDNS_APIURI}/api/v1/api_trusted_blocks -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
Esto devuelve un json con los bloques declarados en la interfaz web:
[
{
"cidr_block": "184.103.220.0/24"
},
{
"cidr_block": "181.122.241.0/24"
},
{
"cidr_block": "200.187.43.157"
}
]
En python3, se podría generar el mismo resultado con el siguiente 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())
Obtención de zonas RPZ activadas (GET, v2.0)
Para los resellers con licencia de Feed RPZ , este endpoint permite obtener las Response Policy Zones activadas.
curl -X GET ${PDNS_APIURI}/api/v1/api_rpz_zones -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}
A continuación se muestra el formato de un hipotético resultado:
[
{
"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"
}
]
Obtención de lista de dominios (GET, v2.0)
La lista completa de dominios de un reseller se obtiene de la siguiente manera:
Warning
Dependiendo de si se va a autenticar con HTTP_RESELLER o HTTP_COMPANY , en cada caso con su respectiva APIKEY, este endpoint devuelve la lista de dominios del Reseller o de la Empresa.
curl -X GET ${PDNS_APIURI}/api/v1/domain_list -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
Warning
Este endpoint solo devuelve dominios activos , es decir dominios que no hayan sido suspendidos. La suspensión de empresas y dominios se introdujo en la versión 2.1
Y aqui se ve un json ejemplo de resultado, con dos dominios:
[
{
"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"
}
]
Los datos recibidos en el json de cada dominio son:
Key |
Explanation |
|---|---|
domain |
nombre del dominio |
type |
tipo es master o slave |
master1 |
en caso de ser slave, el primer master |
master2 |
en caso de ser slave, el segundo master |
soa_serial |
el serial del registro SOA |
allow_axfr |
esto puede ser true o false. Si es true, debe existir una acl para especificar quienes estan habilitados para copiarse el dominio via AXFR |
tsig |
esta es una clave tsig para proteger adicionalmente a dominios que permiten un zone-transfer o AXFR hacia otros servidores |
dnssec |
dice si esta activado DNSSEC, es decir si ya existen registros firmados y esta activado el rollover |
deploy_dnssec |
dice si se debe activar DNSSEC en este dominio |
acl |
aqui va el nombre de la Access Control List declarada para permitir el zone-transfer de este dominio hacia otros servidores |
company |
esta es la empresa, dentro del Reseller, a la cual pertenece este dominio |
Obtención del SOA de un dominio (GET, v2.0)
Esta llamada get lleva el nombre del dominio en la URI , del cual se quiere obtener un JSON con los datos del SOA del dominio assetcrypt.com:
curl -X GET ${PDNS_APIURI}/api/v1/get_soa/assetcrypt.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
El resultado es un json con los datos del 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
}
]
La información del SOA es muy importante para el dominio.
Key |
Explanation |
|---|---|
mname |
Primary Master Name Server |
rname |
Responsible Person’s Email Address |
expire_ttl |
es el tiempo maximo que un secundario puede estar sin refrescar la zona desde el primario. Transcurrido el tiempo maximo, deja de responder por la zona. |
minimum_ttl |
Especifica el mínimo TTL de cada registro de la zona, para cuando el TTL no se especifica en el registro. Es el tiempo de caching de los resolvers por cada RR (Resource Record) |
retry_ttl |
Es el tiempo de backoff que debe esperar un secundario antes de reintentar transferir la zona de un master, en caso de transferencia fallida. |
refresh_ttl |
Es la frecuencia con la cual el secundario va a preguntar al primario si no hay una nueva versión de la zona. |
serial |
Responsible Person’s Email Address |
Note
en PDNS el refresh_ttl muchas veces se ve superpuesto por el mensaje NOTIFY , ya que PDNS genera la lista de zonas con una directiva de notificar a las IPs de los secundarios cada vez que hubo un cambio.
Warning
el serial esta por lo general en modo calendario , siendo YYYYMMDDHH (cuatro dígitos para el año, dos para el mes, dos para el dia, dos para la hora o alternativamente dos digitos de 00 a 99). La interfaz PDNS permite sin embargo especificar, para cada dominio, si está en modo calendario o en modo serial puro que es un número creciente.
Obtener Resource Records de un dominio (GET)
Ejemplo: obtener un JSON con los Resource Records (registros), salvo el SOA que se obtiene aparte, del dominio assetcrypt.com.
curl -X GET ${PDNS_APIURI}/api/v1/domain_rr_list/assetcrypt.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"|jq
El resultado es un JSON representando una 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."
}
]
Note
El valor de rr_prio es numérico, pero se devuelve en forma de string para facilitar la creación de zonas en autoritativos. Solo es necesario en algunos registros como MX.
Note
El valor de rr_id es único, y permite tanto modificar como borrar un registro
Borrar un Resource Record por ID (DELETE)
Se puede borrar un 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 }'
Si no existe o no es parte del dominio que estamos enviando en la URI, devuelve un error 400
Note
el SOA serial de la zona se incrementa automaticamente en 1 (uno)
Crear un Resource Record (POST)
La creación de un RR dentro de una zona, devuelve el ID del mismo.
En este caso creamos un registro dentro de la 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" }'
Warning
Se aplican las restricciones explicadas en el manual de PDNS para CNAMEs, tales como que no se permite la superposicion de CNAMEs con otros registros y por ende la prohibición de CNAME en el APEX de la zona, ya que ahí ya se encuentra el registro SOA.
Note
el SOA serial de la zona se incrementa automaticamente en 1 (uno)
Note
Una zona reversa solo admite registros NS y PTR, aparte del SOA que es creado junto con la zona.
Ejemplo 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"
}'
Warning
En el caso de registros SRV se requieren los siguientes parámetros adicionales:
rr_port(default 443)rr_weightrr_prio(similar al de MX)
El valor rr_value representa el srv host.
El valor final del registro SRV se obtiene concatenando: priority weight port target.
Ejemplo 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"
}'
Warning
En el caso de registros CAA pueden ser necesarios los siguientes parámetros adicionales:
rr_flag(0 o 128)rr_tag(issue,issuewildoiodef)
El dominio de la autoridad certificante se toma del campo rr_value (obligatorio).
Warning
En el caso de registros CAA se encesitarán eventualmente los siguientes parámetros adicionales: rr_flag (0 ó 128), rr_tag (default «issue», puede ser tambien «iodef» o «issuewild»). El host (p.ej. «letsencrypt.org») se toma del rr_value (obligatorio).
Modificar un Resource Record por ID (PUT)
A partir de tener el ID de un RR , se puede modificar su TTL o su valor o también el 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 }'
Note
Al disponer del ID, solo es necesario enviar los campos que se van a modificar. Es decir, no es necesario repetir todo de nuevo.
Note
el SOA serial de la zona se incrementa automaticamente en 1 (uno)
Obtener ACLs de un Reseller (GET)
Las ACLs o Access Control Lists permiten poner permisos de transferencia a aquellos dominios que están permitidos de ser transferidos a otros servidores. Es decir, dominios cuyo contenido completo puede ser copiado.
Cada vez que se permite que un dominio sea transferido, se deben especificar IPv4 o IPv6 en forma individual o en bloque , o una clave criptográfica TSIG que permita a quien lo posea, llevarse una copia del dominio sin importar la IP de origen.
Una ACL lleva un nombre, y es una lista de posibles bloques o ips individuales (es decir /32) IPv4 y/o IPv6 , y posiblemente una clave TSIG.
Por ejemplo, una llamda a la lista de ACLs de un reseller:
curl -X GET ${PDNS_APIURI}/api/v1/get_acls -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"|jq
Un ejemplo de lo que puede devolver este endpoint: dos ACLs, una llamada ACL1 y la otra 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
Estos son los endpoints disponibles en versión 2.1 a Febrero 2024.
Obtención de 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
}
]
Obtención de datos de una Empresa (GET)
Esta llamada GET debe tener un parametro en el JSON de entrada para obtener datos de una empresa llamada “vlans”.
curl -X GET ${PDNS_APIURI}/api/v1/company/vlans -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
El resultado, es un json con datos operativos de esa empresa en particular, como su apikey y si esta suspendida o no.
{
"crm_id": "vlans",
"name": "Vlans",
"apikey": "ru34wbSYPb",
"suspended": false
}
Note
Si quiere obtener un listado de empresas manejadas por el Reseller, debe utilizar la llamada al método companies.
Warning
Si el crm_id enviado en la URL no corresponde a ninguna Empresa, la llamada retorna un HTTP 400 junto con un JSON: {“msg”:”crmid01 does not exist”}
Modificación de datos de una 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}'
Warning
En caso de modificar el valor de suspended , los cambios se harán efectivos hacia todos los dominios de la Empresa.
Note
Si un dominio se encuentra en estado suspended, significa que los servidores autoritativos del Reseller no lo van a anunciar/publicar.
Warning
En caso de cambiar el crm_id , se verificará que sea válido (alfanumérico, solo ‘-‘ y ‘_’ como caracteres especiales permitidos, y se lo pasará todo a minúscula por tratarse de una clave de búsqueda)
Warning
En caso de cambiar apikey, se removerán todos los espacios, ‘,’ y ‘;’, dado que no están permitidos como parte de una clave API.
Creación de una Empresa (POST)
Se debe enviar un crm_id con las restricciones definidas anteriormente, un name o nombre, y una apikey. El estado inicial de suspended es False, es decir la empresa está activa para que todos los dominios que se le asocien, estén a su vez activos por default a medida que vayan siendo creados.
El endpoint chequea que el crm_id no exista previamente, y que se le proporcionen name y apikey como parámetros obligatorios.
curl -X POST ${PDNS_APIURI}/api/v1/company/nuevaempresa1 -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "name":"Nueva Empresa1", "apikey": "newapikey001" }'
En caso de ya existir el crm_id , la API devuelve un error 400 y un mensaje {“msg”:”Company nuevaempresa1 already exists”}
Borrado de una Empresa (DELETE)
Se debe enviar un crm_id con las restricciones definidas anteriormente, la apikey de la empresa por seguridad, para reafirmar el pedido.
El endpoint chequea que el crm_id exista, sino devuelve un error 400 con un mensaje {“msg”:”Company empresaxyz does not exist”}.
Warning
Este endpoint borra todos los dominios que pertenezcan a la empresa.
curl -X DELETE ${PDNS_APIURI}/api/v1/company/empresaxyz -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "apikey": "company_apikey001" }'
Note
Se recomienda suspender a una empresa en caso de dar de baja, y recién transcurrido un cierto tiempo, proceder a un cleanup a través del borrado.
Creación de una zona master (POST)
Para crear una zona master, se debe especificar a qué empresa pertenece (crm_id), y un fqdn o Fully Qualified Domain Name (este ultimo en la URI). El nombre no necesita ser reconocido en el Internet, porque puede tratarse de una zona nueva o de una zona interna. Además, se deberán proveer datos para el registro SOA.
El tipo de serial SOA puede ser numeric o calendar (en este último caso es YYYYMMDDSS, siendo SS un valor de 0 a 99). En el caso de calendar , la cantidad de cambios se limita a 100 por día.
Ejemplo:
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"
}'
Si falta alguno de los datos, el endpoint devuelve un error 400 diciendo que falta un campo. También hace chequeos de consistencia, p.ej. respecto al mname o Master DNS Name, que lo pone como registro NS automáticamente al crear la zona, y también crea el registro SOA con los datos proporcionados.
En caso de existir la zona dentro del Reseller, devolverá un error 400 con un mensaje de Zona duplicada.
La zona se crea con el parámetro suspended en False, es decir la zona se activa inmediatamente.
Cambio de SOA o empresa de una zona (PUT)
Este es un caso de cambio de metadatos de una zona, simplemente se deberá proveer nuevos valores , ya sea para el SOA o la empresa, o inclusive cambiar el serial_type. También sirve para incrementar artificalmente el SOA de una 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" }'
Note
Solo es necesario proveer aquellos valores que se vayan a modificar
Zona master reversa
Respecto a la creación de zonas, valen las siguientes acotaciones:
Warning
en caso que la zona termine en in-addr.arpa o ip6.arpa , la zona será considerada reversa en vez de directa. Esta metadata no se puede cambiar.
Note
A diferencia de la interfaz web, en donde se utiliza la notación directa de una /24, p.ej. 123.221.24.0/24 para denotar la creación de una zona reversa, en la API utilizamos 24.221.123.in-addr.arpa directamente como nombre de la zona. Actualmente PDNS solo soporta zonas /24 para registros PTR.
Note
Por ejemplo, una zona IPv6 0.0.0.0.0.0.c.b.3.0.8.2.ip6.arpa representa una /40 , con valores como p.ej. 2803:bc00::9A, el valor extendido es 2803:bc00:0000:0000:0000:0000:0000:009a. En caso de querer representar la zona 2803:bc00:0000::/64 , el nombre de la zona es más largo 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
Creación de una zona slave (POST)
Para crear una zona slave, se debe especificar a qué empresa pertenece (crm_id), un fqdn o Fully Qualified Domain Name, y las master-ips. El nombre no necesita ser reconocido en el Internet, porque puede tratarse de una zona nueva o de una zona interna. Las master-ips pueden ser una o dos, son direcciones IP de donde el autoritativo del Reseller va a intentar transferirse la zona.
Warning
esta versión no soporta claves TSIG, ver secure_slave_zone para crear una zona esclava protegida con clave TSIG
Ejemplo:
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" }'
Si falta alguno de los datos, el endpoint devuelve un error 400 diciendo que falta un campo.
Note
Solo masterip1 es obligatorio
En caso de existir la zona dentro del Reseller, devolverá un error 400 con un mensaje de Zona duplicada.
La zona se crea con el parámetro suspended en False, es decir la zona se activa inmediatamente.
Warning
en caso que la zona termine en in-addr.arpa o ip6.arpa , la zona será considerada reversa en vez de directa. Esta metadata no se puede cambiar.
Suspensión y Reanudación de una zona (PUT)
Una zona se puede reanudar y suspender sucesivamente utilizando llamadas PUT a los siguientes endpoints, p.ej.:
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"}'
Note
Suspender una zona significa que no se publica en los DNSs autoritativos correspondientes al Reseller, donde se encuentra la Empresa a la cual pertenece la zona. Sin embargo, se pueden realizar modificaciones via Web o API a los registros de la zona, ya que los mismos se encuentran disponibles.
Borrado de una zona (DELETE)
Para borrar una zona, se deberá simplemente utilizar el método DELETE , con lo cual se borrarán también todos sus Resource Records incluyendo el SOA. La zona dejará de publicarse y sus registros no estarán más disponibles.
Ejemplo:
curl -X DELETE ${PDNS_APIURI}/api/v1/domain -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{"domain": "test.com", "crm_id": "test1"}'
Warning
Una vez borrada la zona, no queda ningún rastro de la misma.
Endpoints v2.2
Estos son los endpoints disponibles en versión 2.2 previsto para agosto 2024.
Creación de una slave TSIG (POST)
Ejemplo de key en formato bind9, generada con /usr/sbin/tsig-keygen hola1
key "hola1" {
algorithm hmac-sha256;
secret "LvzAji80xCrq7eoD5YODSDjD0LLJLiX2nWPGSA11q1w=";
};
El endpoint para crear una clave TSIG y publicarla en bind9, precisa de un nombre y un algoritmo. El algoritmo debe ser uno de los siguientes:
hmac-md5 |
hmac-sha1 |
hmac-sha224 |
hmac-sha256 |
hmac-sha384 |
hmac-sha512 |
Este ejemplo crea una key con nombre keyname con algoritmo hmac-256.
curl -X POST ${PDNS_APIURI}/api/v1/createkey/newkey -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" -d '{ "algorithm": "hmac-sha512" }'
La llamada devuelve la clave en base 64
{
"algorithm": "hmac-sha512",
"keyname": "newkey",
"secret": "STe13VSVnkXdCXoe/ibjpSxzviqnGqb20VJhkDEc54cmNP3z3/s+qURW1feeYylwWa6L0hdTyHMBxivK2x2zOQ=="
}
Borrado de una slave TSIG (DELETE)
El borrado solo es posible siempre y cuando no haya zonas slave que la necesiten.
curl -X DELETE ${PDNS_APIURI}/api/v1/createkey/newkey -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
Creación de una zona slave segura (POST)
A diferencia del endpoint slave_zone, este endpoint secure_slave_zone permite declarar una lista de master IPs (no limitada a dos , como en el caso de slave_zone) y con una clave adicional TSIG.
Adicionalmente, se puede agregar TSIG o clave criptográfica, si esta es requerida por el servidor que pone a disposición la zona, especificando el nombre de la 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" }'
De esta manera, si el administrador de una zona expone dicha zona a través de varias IPs y una clave TSIG, debemos crear la clave primero con createkey , y luego agregar su nombre en esta llamada a secure_slave_zone de manera de asociar la key a las IPs maestras (de donde, elegidas al azar, se va a intentar traer la zona a nuestro primario del Reseller correspondiente).