Documentación API PDNS
La documentación estará documentada en bash con el comando curl , y algunos ejemplos en python v3.8+.
La API es REST y solo se comunica via HTTPS con TLSv1.2 como mínimo, aunque en futuras versiones solo se permitirá negociar a partir de TLSv1.3 dado el gap de seguridad con versiones anteriores y la posiblidad de RTT que ofrece v1.3.
Versiones de PDNS-API
Existen muy pocos endpoints en la versión 2.0, y son destinados a intervenir dinámicamente la configuración de los resolvers y autoritativos.
Recién a partir de la versión 2.1 se proveen más endpoints, como para poder construir un CRM o una Aplicación sin necesidad de utilizar para nada la interfaz web.
Autenticacion y Métodos
La autenticación está orientada a Resellers dentro de la tenencia múltiple. Se deben especificar dos encabezados para permitir la autorización:
Reseller |
Authorization |
En el enacabezado Reseller va el crm-id o short-name (no el nombre largo completo) del Reseller.
En el encabezado Authorization va la APIKEY asignada al Reseller.
De acuerdo a la política de seguridad y a la capacidad de orquestación de la organización que vaya a implementar la API , puede hacer rollover de sus APIKEYs con frecuencia.
Se recomienda guardar ambos datos en variables de environment, ya sea propios de una aplicación (p.ej. en un .env) o globales de un container o servidor p.ej. en ~/.bashrc
Por ejemplo variables de environment de bash:
export PDNS_APIURI="https://api-server.cirion.live"
export PDNS_RESELLER="reseller01"
export PDNS_APIKEY="api-key-QueeSihuak2aegai"
Advertencia
En una próxima futura versión se incorporarán APIKEYs a nivel Empresa por debajo de un Reseller , p.ej. para que una empresa tenga la autonomía de implementar un esquema de failover (e.g. monitorear un sitio mirroreado, y cambiar la IP al mirror si se cae el sitio principal) sin recurrir a su proveedor.
Los métodos permitidos son
GET |
POST |
PUT |
DELETE |
El método GET es para obtener una información.
El método POST es para introducir un elemento nuevo o modificarlo.
El método PUT es para modificar elementos existentes.
El método DELETE es para borrar elementos.
Nota
Los ejemplos se muestran mayormente en un hipotético entorno bash con las variables de environment descriptas.
Endpoints v2.0
A continuación se exponen los métodos v2.0 destinados a interactuar con la configuración del bind9, y también en general a obtener información sobre los datos ingresados en la interfaz web.
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:
Advertencia
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}"
Advertencia
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 |
Nota
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.
Advertencia
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."
}
]
Nota
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.
Nota
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
Nota
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" }'
Advertencia
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.
Nota
el SOA serial de la zona se incrementa automaticamente en 1 (uno)
Nota
Una zona reversa solo admite registros NS y PTR, aparte del SOA que es creado junto con la zona.
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 }'
Nota
Al disponer del ID, solo es necesario enviar los campos que se van a modificar. Es decir, no es necesario repetir todo de nuevo.
Nota
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
}
Nota
Si quiere obtener un listado de empresas manejadas por el Reseller, debe utilizar la llamada al método companies.
Advertencia
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}'
Advertencia
En caso de modificar el valor de suspended , los cambios se harán efectivos hacia todos los dominios de la Empresa.
Nota
Si un dominio se encuentra en estado suspended, significa que los servidores autoritativos del Reseller no lo van a anunciar/publicar.
Advertencia
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)
Advertencia
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»}.
Advertencia
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" }'
Nota
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" }'
Nota
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:
Advertencia
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.
Nota
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.
Nota
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.
Advertencia
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.
Nota
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.
Advertencia
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}"
curl -X PUT ${PDNS_APIURI}/api/v1/resume_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}"
Nota
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"}'
Advertencia
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).