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: .. list-table:: Encabezados (Headers) * - 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: .. code:: export PDNS_APIURI="https://api-server.cirion.live" export PDNS_RESELLER="reseller01" export PDNS_APIKEY="api-key-QueeSihuak2aegai" .. warning:: 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 .. list-table:: Encabezados (Headers) * - 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. .. note:: 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: .. code-block:: bash 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: .. code-block:: json [ { "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: .. code-block:: python 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. .. code-block:: bash 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: .. code-block:: json [ { "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. .. code-block:: bash 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: .. code-block:: json [ { "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: .. list-table:: domain_list :widths: 10, 90 :header-rows: 1 * - 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**: .. code-block:: bash 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**) .. code-block:: json [ { "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. .. list-table:: start of authority record :widths: 10, 90 :header-rows: 1 * - 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**. .. code-block:: bash 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: .. code-block:: json [ { "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 .. code-block:: bash 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** .. code-block:: bash 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. 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: .. code-block:: bash 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: .. code-block:: bash 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` .. code-block:: json [ { "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) ++++++++++++++++++++++++++++++++++++ .. code-block:: bash curl -X GET ${PDNS_APIURI}/api/v1/companies -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" .. code-block:: json [ { "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". .. code-block:: bash 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. .. code-block:: json { "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. .. code-block:: bash 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. .. code-block:: bash 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. .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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.: .. code-block:: bash curl -X PUT ${PDNS_APIURI}/api/v1/suspend_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" .. code-block:: bash curl -X PUT ${PDNS_APIURI}/api/v1/resume_zone/dom1.com -H "Authorization: ${PDNS_APIKEY}" -H "Reseller: ${PDNS_RESELLER}" .. 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: .. code-block:: bash 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 .. code:: code 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: .. list-table:: Algoritmos TSIG * - hmac-md5 * - hmac-sha1 * - hmac-sha224 * - hmac-sha256 * - hmac-sha384 * - hmac-sha512 Este ejemplo crea una key con nombre ``keyname`` con algoritmo *hmac-256*. .. code-block:: bash 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 .. code-block:: hash { "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. .. code-block:: bash 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. .. code-block:: 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).